可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本文基于 highlight.io 官方仓库中的 Azure Functions 示例应用e2e/python/highlight_azure讲解如何在 Python 编写的 Azure Functions 项目中接入 highlight.io 的日志采集、错误监控与分布式追踪能力。读完本文你将掌握 Azure Functions Python 项目的标准目录结构、highlight.io 的observe_handler装饰器用法、本地开发与发布上云流程以及如何用 SDK 自带测试验证观测数据是否正确上报。背景为什么要在 Azure Functions 里做可观测性Azure Functions 是典型的事件驱动、按需伸缩的无服务器计算平台函数实例由平台托管、生命周期短暂、可能被频繁回收。这种用完即走的特性带来一个观测难题传统的常驻进程式日志采集与链路追踪方案在函数场景下常常失效——请求结束后进程立刻销毁日志和追踪数据来不及上报就会丢失。highlight.io 的全栈监控方案错误监控、Session 回放、日志、分布式追踪恰好覆盖了这一场景本仓库中即提供了面向 Azure Functions 的官方集成示例。Azure Functions Python 项目的标准目录结构官方脚手架生成的项目project_root中各文件职责如下这也是 e2e/python/highlight_azure 示例所遵循的规范文件/目录作用是否发布到 Azurelocal.settings.json存储本地运行时的应用设置与连接字符串否requirements.txt声明 Python 依赖包发布时系统自动安装是host.json函数应用的全局配置影响所有函数是.vscode/可选的 VS Code 编辑器配置否.venv/本地开发使用的 Python 虚拟环境否Dockerfile可选用于以自定义容器方式发布项目否tests/可选存放函数应用的测试用例否.funcignore声明不随项目发布到 Azure 的文件通常包含.vscode/、.venv/、tests/、local.settings.json否function.json每个函数各自的绑定配置文件是每个函数都由一对文件组成函数代码文件如__init__.py和绑定配置文件function.json。在 e2e/python/highlight_azure/HttpTrigger 目录下可以看到本示例的这对文件__init__.py函数主入口被observe_handler装饰器包裹function.json声明该函数的 HTTP 触发器绑定。注意.venv/、.vscode/这类本地开发产物务必通过.funcignore排除避免把本地环境泄露到云端local.settings.json中的连接字符串属于敏感信息也不应发布。在函数入口接入 highlight.io本仓库的示例函数 HttpTrigger/init.py 展示了完整的接入方式核心只有三步import logging import random import time from datetime import datetime import azure.functions as func import highlight_io from highlight_io.integrations.azure import observe_handler # 1. 初始化 highlight 客户端 H highlight_io.H(1, instrument_loggingTrue) # 2. 用装饰器包裹函数入口 observe_handler def main(req: func.HttpRequest) - func.HttpResponse: start datetime.now() logging.info(Python HTTP trigger function processed a request.) logging.info( Python Azure hello handler, {customer: req.headers.get(customer) or unknown}, ) # 模拟业务逻辑产生的日志 for idx in range(int(1000 random.random() * 10000)): logging.info( Python Azure emitting log f{idx} idx, { customer: req.headers.get(customer) or unknown, idx: idx, float: 1.2345, duration: (datetime.now() - start).total_seconds(), }, ) # 随机抛错用于验证错误监控 if random.random() 0.2: raise ValueError(oh no!) name req.params.get(name) if not name: try: req_body req.get_json() except ValueError: pass else: name req_body.get(name) time.sleep(5) logging.info( Python Azure got name, { customer: req.headers.get(customer) or unknown, name: name, float: 1.2345, duration: (datetime.now() - start).total_seconds(), }, ) # 3. 返回标准 HTTP 响应 if name: return func.HttpResponse( fHello, {name}. This HTTP triggered function executed successfully. ) else: return func.HttpResponse( This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response., status_code200, )要点拆解highlight_io.H(1, instrument_loggingTrue)创建全局 highlight 客户端1为示例项目 ID实际使用时替换为你的项目 IDinstrument_loggingTrue开启对标准logging模块的自动接入使函数内所有logging.info(...)调用自动上报为 highlight 日志且附带结构化字段customer、idx、float、duration等。observe_handler装饰器自动完成三件事——从请求头提取 highlight 会话/请求 ID 建立关联、为整个函数调用开启一条名为observe_serverless的 trace、捕获并上报未捕获异常如示例中的ValueError(oh no!)。日志中的duration字段展示了如何将业务耗时等上下文一并写入观测数据便于后续在 highlight 控制台按字段过滤检索。observe_handler 装饰器的底层原理observe_handler的实现位于 sdk/highlight-py/highlight_io/integrations/azure.pyfrom highlight_io import H from highlight_io.integrations.serverless import observe_serverless def observe_handler(fn): Decorator for serverless request handlers. Extracts the request context to associate the request in azure functions. :param fn: a function handler that the decorator is applied to. :return: a wrapped function that will record exceptions. def get_highlight_header(*args, **kwargs): highlight_header_value: str if args and args[0] and args[0].headers and callable(args[0].headers.get): highlight_header_value args[0].headers.get(H.REQUEST_HEADER) or return highlight_header_value return observe_serverless(get_highlight_header, fn)它只做一件事从 Azure Functions 的HttpRequest即装饰函数的第一个位置参数的 headers 中取出H.REQUEST_HEADER对应的 header 值然后交给通用的无服务器观测装饰器 observe_serverlessdef observe_serverless(get_highlight_header, fn): functools.wraps(fn) def wrapper(*args, **kwargs): session_id, request_id , try: session_id, request_id get_highlight_header(*args, **kwargs).split(/) except ValueError: pass try: with H.get_instance().trace(observe_serverless, session_id, request_id): return fn(*args, **kwargs) finally: # cloud functions may terminate quickly after response is sent. # flush to make sure logs / traces are delivered. H.get_instance().flush() return wrapper关键机制有三点请求关联highlight 前端 SDK 会向服务端请求注入形如session_id/request_id的 header 值装饰器解析这个值后把当前函数调用与具体的会话、请求关联起来实现从前端到后端的全链路贯通。自动追踪整个函数体被包进H.get_instance().trace(observe_serverless, session_id, request_id)上下文函数执行耗时、过程中产生的日志都与这条 trace 绑定。强制冲刷finally块中的H.get_instance().flush()是函数场景的救命稻草——无服务器平台可能在响应发送后立刻销毁进程必须在函数结束前主动冲刷缓冲区确保日志与追踪数据已经送达。依赖声明与函数配置requirements.txte2e/python/highlight_azure/requirements.txt 中声明了两个包# Do not include azure-functions-worker in this file # The Python Worker is managed by the Azure Functions platform # Manually managing azure-functions-worker may cause unexpected issues azure-functions highlight-io注意文件中的注释切勿手动把azure-functions-worker写进 requirements.txt——Python Worker 由 Azure Functions 平台托管管理手动指定版本可能导致运行时异常。azure-functions提供func.HttpRequest/func.HttpResponse等类型highlight-io提供观测 SDK。function.jsonHttpTrigger/function.json 声明了 HTTP 触发器绑定{ scriptFile: __init__.py, bindings: [ { authLevel: anonymous, type: httpTrigger, direction: in, name: req, methods: [get, post] }, { type: http, direction: out, name: $return } ] }scriptFile指向函数入口脚本__init__.pyauthLevelanonymous表示无需函数密钥即可调用便于测试验证methods允许get与post两种请求方法对应示例代码中既支持 URL 参数req.params.get(name)又支持 JSON bodyreq.get_json()的取值逻辑输出绑定$return表示函数返回值直接作为 HTTP 响应。host.jsonhost.json 是函数应用的全局配置本示例包含两个关键项{ version: 2.0, logging: { applicationInsights: { samplingSettings: { isEnabled: true, excludedTypes: Request } } }, extensionBundle: { id: Microsoft.Azure.Functions.ExtensionBundle, version: [3.*, 4.0.0) } }version: 2.0host.json 的架构版本applicationInsights.samplingSettings启用 Application Insights 采样并对Request类型豁免采样保证请求级观测完整extensionBundle声明使用微软官方扩展捆绑包Microsoft.Azure.Functions.ExtensionBundle版本范围[3.*, 4.0.0)让函数运行时自动获得所需的绑定扩展。host.json 会被发布到 Azure影响所有函数部分选项在本地运行时不受支持以官方文档为准。用 VS Code 开发第一个 Python 函数开发流程与标准 Azure Functions 一致若尚未准备环境先完成 Azure Functions 的 Python 快速入门安装 Azure Functions Core Tools、VS Code 的 Azure Functions 扩展、Python 3.x 环境在 VS Code 中打开项目根目录利用扩展创建/调试函数本仓库示例自带了 .vscode/extensions.json 来声明推荐的 VS Code 扩展本地调试时使用local.settings.json提供应用设置与连接字符串该文件不会发布到 Azure按上文接入highlight_io后直接运行函数并携带 highlight 的会话 header 发起请求即可在本地验证观测数据。发布函数应用到 Azure发布前建议对照 .gitignore 与.funcignore检查排除项确保本地产物.vscode/、.venv/、local.settings.json、tests/不会进入云端。发布方式主要有三种VS Code 发布使用 Azure Functions 扩展的Deploy to Function App...命令选择目标 Function App 后一键部署Azure Functions Core Tools在项目根目录执行func azure functionapp publish APP_NAME自定义容器若项目包含Dockerfile可将函数应用打包为自定义容器镜像发布。发布后函数运行时会按requirements.txt自动安装依赖host.json与各function.json同步生效。用测试验证观测链路SDK 仓库提供了针对该集成装饰器的自动化测试 sdk/highlight-py/tests/test_azure.py它模拟了真实函数调用并断言追踪关联是否生效import logging import random import azure.functions as func import pytest from highlight_io import H from highlight_io.integrations.azure import observe_handler observe_handler def main(req: func.HttpRequest) - func.HttpResponse: logging.info(Python HTTP trigger function processed a request.) if random.random() 0.2: raise ValueError(oh no!) return func.HttpResponse( fHello! This HTTP triggered function executed successfully. ) def test_azure(mocker): mocker.patch(random.random, return_value0.1) mock_trace mocker.spy(H, trace) # Construct a mock HTTP request. req func.HttpRequest( methodGET, bodyNone, url/api/my_second_function, headers{H.REQUEST_HEADER: a1b2c3/1234}, params{value: 21}, ) with pytest.raises(expected_exceptionValueError): main(req) mock_trace.assert_called_with( H.get_instance(), observe_serverless, a1b2c3, 1234 )这段测试验证了两个核心事实当请求头携带H.REQUEST_HEADER: a1b2c3/1234时装饰器正确解析出session_ida1b2c3、request_id1234装饰器内部以H.get_instance().trace(observe_serverless, a1b2c3, 1234)开启了关联追踪函数内抛出的ValueError会被装饰器捕获上报同时异常照常向调用方传播pytest.raises仍能捕获。这个测试同时演示了向 highlight 上报数据的真实调用方式H.get_instance().trace(name, session_id, request_id)是 SDK 的核心追踪接口flush()负责在函数结束前将缓冲数据送达。下一步深入无服务器可观测性将highlight_io.H(...)的示例项目 ID 替换为你的真实项目 ID并在函数应用所在环境配置对应的项目密钥前端接入 highlight SDK 后携带的会话 header 会自动与这里的后端 trace 关联形成前后端一体的全链路视图关注 sdk/highlight-py 下highlight_io/integrations/目录的更多实现该目录除 Azure 外还覆盖了其他无服务器平台的集成可对比 serverless.py 中的通用observe_serverless机制参考 SDK 的 pyproject.toml其中声明了azure-functions ^1作为测试依赖了解运行测试所需的环境。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐使用 highlight.io 监控 Python Django 应用错误、日志与分布式追踪接入实战使用 highlight.io 监控 Python Django 应用错误、日志与分布式追踪接入实战 本篇技术指南讲解如何将开源全栈可观测平台 highlig可观测性后端highlight.io 接入 Python FastAPI错误监控、日志采集与分布式追踪完整指南highlight.io 接入 Python FastAPI错误监控、日志采集与分布式追踪完整指南 本篇指南围绕 highlight.io 官方为 Pytho可观测性后端使用 highlight.io 监控 Python Flask 后端错误、日志与分布式追踪接入指南使用 highlight.io 监控 Python Flask 后端错误、日志与分布式追踪接入指南 highlight.io 是一个开源的 Full stac可观测性后端上一篇APK-Installer在Windows上安装Android应用的终极完整指南下一篇Cursor Pro破解工具5分钟掌握永久免费使用AI编程助手的高级功能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考