highlight-io Python SDK 开发与本地调试指南：安装、e2e 示例应用、测试与集成架构

可观测性后端【免费下载链接】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 开源仓库中 sdk/highlight-py/README.md 为骨架系统讲解 highlight-io Python SDK 的本地开发环境搭建、四个 e2e 示例应用Django、Flask、FastAPI、Loguru的启动方式以及测试与代码风格检查命令。文章同时结合 sdk.py 与highlight_io/integrations目录的源码深入剖析H类的初始化参数、OTLP 数据导出、session/request 关联、日志埋点与框架自动插桩等底层机制帮助读者既能在本地跑通 SDK 的完整开发闭环又能理解其可观测性数据链路的实现原理。文档定位这是一份 SDK 开发者指南而非最终用户使用手册该 README 面向的对象是 highlight-io Python SDK 的贡献者与开发者而非直接使用 SDK 的普通应用开发者。它的核心内容分为四块e2e 说明e2e目录下存放着接入 SDK 的受支持 Python 框架示例应用用于本地开发与联调并明确警告不要逐字照搬这些片段它们是针对本地开发配置的不经过修改无法用于生产环境安装步骤基于 Poetry 的依赖安装运行 e2e 应用Django、Flask、FastAPI含 Redis、AWS、Celery、Loguru 四个示例的启动命令测试与 Lintpytest与black的用法。从仓库实际布局看README 中提到的e2e目录对应仓库根目录下的 e2e/python其中highlight_django、highlight_flask、highlight_fastapi、highlight_loguru等子目录即为各框架示例SDK 源码本体则位于sdk/highlight-py/highlight_io/与 tests 测试目录。认识 highlight-io Python SDK包结构与能力概览包的顶层导出在 sdk/highlight-py/highlight_io/init.py 中SDK 对外只暴露三个核心对象from highlight_io.sdk import H, trace __all__ [H, integrations, trace]H核心类负责初始化 Tracer/Logger/Meter Provider、注册集成、提供手动埋点 APItrace函数装饰器用H.get_instance().trace(span_namefunc.__name__)包裹任意函数自动把该函数执行过程记录为一个 spanintegrations框架/库集成模块位于 highlight_io/integrations。依赖底座OpenTelemetry 全家桶从 pyproject.toml 可以清晰看到该 SDK 是构建在 OpenTelemetry Python 生态之上的发行版式封装opentelemetry-api / sdk / proto / exporter-otlp-proto-grpc提供 Trace、Logs、Metrics 三支柱的数据模型与 OTLP/gRPC 导出能力覆盖数十个第三方库的opentelemetry-instrumentation-*包括 aiohttp、anthropic、bedrock、boto、boto3sqs、celery、chromadb、cohere、django、fastapi、flask、grpc、haystack、httpx、jinja2、langchain、llamaindex、openai、pinecone、psycopg、qdrant、redis、replicate、requests、sqlalchemy、sqlite3、starlette、system-metrics、transformers、urllib、urllib3、vertexai、watsonx、weaviate、wsgi 等urllib3、requests作为基础 HTTP 依赖Python 版本约束为3.9,4当前 SDK 版本为0.10.1License 为 Apache-2.0。由此可见highlight-io Python SDK 的定位是把 OpenTelemetry 的标准插桩能力与 highlight.io 的会话回放Session Replay/错误监控/日志/追踪平台打通开发者只需少量配置即可获得全栈可观测性。环境准备与安装README 给出的安装方式完全基于 Poetry先安装 poetry 包管理器进入 SDK 目录即 sdk/highlight-py执行poetry install --all-extras--all-extras会一次性安装全部集成所需的依赖包括 pyproject.toml 中[tool.poetry.group.dev.dependencies]声明的开发依赖django、flask、fastapi、loguru、orjson、pytest、pytest-asyncio、pytest-cov、pytest-mock、black、blinker、azure-functions、functions-framework等。这些正是运行 e2e 示例和测试所必需的。运行 e2e 示例应用README 提供了四个框架的本地启动方式。注意仓库中这些示例应用位于 e2e/python 下以下命令均假定已在对应示例目录内执行。Djangocd e2e/python/highlight_django poetry run python manage.py runserver示例应用位于 e2e/python/highlight_django包含 Django 项目骨架polls应用、manage.py等。对应集成源码见 highlight_io/integrations/django.py它通过包装WSGIHandler.__call__捕获每个请求并监听 Django 的got_request_exception信号把未捕获异常上报到 Highlight。Flaskcd e2e/python/highlight_flask poetry run flask run示例应用位于 e2e/python/highlight_flask包含app.py、models.py、database.py。对应集成源码见 highlight_io/integrations/flask.py通过包装Flask.__call__包裹 WSGI 调用链并连接 Flask 的got_request_exception信号上报异常。FastAPI含 Redis、AWS 与 CeleryFastAPI 示例是四个示例中最复杂的README 给出了完整的三步准备流程第一步启动 Rediscd docker ./start_infra # 用于启动 Redis仓库中对应的实际脚本为 docker/start-infra.sh它会拉起本地基础设施其中包含 Redis供示例中的队列相关功能使用。第二步配置 AWSBoto/Boto3环境变量在 PyCharm 的 Run Configuration运行配置中设置以下环境变量E2E_AWS_ACCESS_KEY来自 IAM 账户E2E_AWS_SECRET_KEY来自 IAM 账户SQS_QUEUE_URL来自 SQS 队列信息这些变量会被示例中的 SQS/Boto3 集成消费用于演示基于消息队列的异步链路追踪。第三步启动主应用与 Celery workercd e2e/python/highlight_fastapi poetry run uvicorn main:appcd e2e/python/highlight_fastapi poetry run celery -A e2e.highlight_fastapi.work worker --loglevelINFO示例应用位于 e2e/python/highlight_fastapi其中main.py为主入口、work.py为 Celery 任务定义这也是-A e2e.highlight_fastapi.work模块路径的由来。对应集成源码见 highlight_io/integrations/fastapi.pyFastAPIMiddleware与 highlight_io/integrations/celery.py基于CeleryInstrumentor自动插桩。Logurucd e2e/python/highlight_loguru poetry run python main.py示例应用位于 e2e/python/highlight_loguru。Loguru 的接入方式与标准logging不同——SDK 通过H.logging_handler属性返回一个实现了logging.Handler协议的处理器Loguru 用logger.add(H.logging_handler, ...)挂接即可具体可参考 sdk.py 中 LogHandler 的实现。使用 e2e 应用的注意事项README 特别强调e2e 目录中的示例片段不要逐字照搬到生产环境。它们为了本地联调便利性做了大量简化例如使用本地 Redis、硬编码配置、开发服务器生产部署时必须替换为正式的接入方式在 highlight.io 官方文档 中可找到对应的生产集成指引。运行测试与代码规范检查单元测试poetry run pytest测试代码位于 sdk/highlight-py/tests覆盖了 SDK 的各个集成点包括test_sdk.py、test_fastapi.py、test_django.py、test_flask.py、test_celery.py、test_loguru.py、test_redis.py、test_requests.py、test_sqlalchemy.py、test_aws.py、test_azure.py、test_boto.py、test_boto3sqs.py、test_gcp.py、test_utils_dict.py等。以 tests/test_fastapi.py 为例它通过参数化测试验证了FastAPIMiddleware对普通响应、4xx 响应、流式响应及异常场景的处理并将otlp_endpoint指向http://localhost:4317进行本地断言是理解集成行为的最佳入口。代码风格poetry run black .SDK 使用 Black 作为统一代码格式化工具pyproject.toml 的 dev 依赖组中已声明black ^24。源码级解读SDK 的可观测性数据链路H类的初始化参数与默认 OTLP 端点H类的构造函数定义在 sdk.py 第 90 行起关键参数及语义如下参数默认值说明project_id必填对应app.highlight.io/setup中项目的 verbose id会写入 span attributehighlight.project_idintegrationsNone显式传入的框架级集成列表如 Django/Flask/FastAPIdisabled_integrationsNone需要禁用的默认集成 key 列表otlp_endpointhttps://otel.highlight.io:4317自定义 OTLP gRPC 目标地址类常量H.OTLP_HTTPinstrument_loggingTrue是否自动插桩 Python 标准logginglog_levellogging.INFO日志级别service_name/service_version/environment对应 OTel Resource 的service.name、service.version、deployment.environmentdisable_export_error_loggingFalse为True时把 OTLP 导出器相关 logger 提升到 FATAL抑制导出错误刷屏debugFalse开启后把根 logger 设为 DEBUG 并输出到 stdout初始化时会创建三类 OTel Provider并各自挂上 OTLP/gRPC 导出器均启用 Gzip 压缩对应三条数据通道TraceTracerProviderBatchSpanProcessorOTLPSpanExporter端点{otlp_endpoint}/v1/tracesLogsLoggerProviderBatchLogRecordProcessorOTLPLogExporter端点{otlp_endpoint}/v1/logsMetricsMeterProviderPeriodicExportingMetricReaderOTLPMetricExporter端点{otlp_endpoint}/v1/metrics。批量导出参数schedule_delay_millis5000、max_export_batch_size128*1024、max_queue_size1024*1024在构造函数中统一写入 kwargs防止海量 trace/log 导致 OOM这也是 CHANGELOG.md 中 v0.6.1 的修复重点。H.flush()会依次force_flush()三个 Provider。session/request 关联X-Highlight-Request 头highlight-io 与前端会话回放session replay打通的关键是X-Highlight-Request请求头。前端 SDK 在发起网络请求时会携带形如session_id/request_id的头部框架集成如 fastapi.py 中的FastAPIMiddleware、django.py、flask.py在请求入口解析该头并传入H.trace(...)H.trace()上下文管理器sdk.py会把(session_id, request_id)写入一个容量为 1000 的 LRU 缓存_context_map注释说明Python 进程是单线程的不需要超过 1000 条并把二者写入 span 的highlight.session_id/highlight.trace_id属性自定义的HighlightSpanProcessor.on_start还会通过 OpenTelemetry Baggage 传递该头确保跨 span 传播。手动埋点 APIH类提供一组可直接调用的记录 API均要求当前存在可记录的 span 上下文record_exception(e, attributes)记录任意异常及其堆栈sdk.pyrecord_http_error(status_code, detail, attributes)以HTTPException事件形式记录 HTTP 错误会解析{detail: ...}形式的响应体空 detail 时回退到http.HTTPStatus的标准短语sdk.pyrecord_metric / record_count / record_incr / record_histogram / record_up_down_counter分别基于 OTel 的 Gauge、Counter、Histogram、UpDownCounter 上报指标同名指标与属性会在 OTel SDK 内聚合sdk.py。FastAPIMiddleware就是record_http_error的典型消费者当响应状态码 400时此时HTTPException不会向上抛出中间件把请求/响应头与方法、URL 一并作为 attributes 上报为异常事件。日志集成与 LogHandlerH初始化时默认调用_instrument_loggingsdk.py通过LoggingInstrumentor插桩标准库logging并覆写logging.getLogRecordFactory()若当前无活跃 span则自动用H.trace(highlight.log)包裹日志记录。LogHandlersdk.py 第 56 行起则供用户把 SDK 接入既有日志体系例如import logging formatter logging.Formatter( %(name)s :: %(levelname)-8s :: %(message)s) handler H.logging_handler handler.setFormatter(formatter) lg logging.getLogger(my.logger) lg.addHandler(handler) lg.warning(oh, no!)log_hook会把日志记录映射为 OTel LogRecord填充code.function、code.namespace、code.filepath、code.lineno等语义约定属性关联highlight.trace_id/highlight.session_id若日志带有异常信息exc_info则转为record_exception同时还兼容 LoguruserializeTrue序列化格式自动解析record[extra]附加字段。框架/库集成机制与默认启用列表集成抽象定义在 highlight_io/integrations/init.pyIntegration是抽象基类子类声明INTEGRATION_KEY并实现instrumentor()importer()会检查依赖冲突_check_dependency_conflicts()依赖缺失或冲突时优雅降级为NoopInstrumentor仅记录 debug 日志不会导致应用启动失败enable()/disable()控制插桩的启停。all.py 定义了 21 个默认启用的集成Anthropic、Bedrock、Boto3SQS、Boto、Celery、Chromadb、Cohere、Haystack、Langchain、LlamaIndex、OpenAI、Pinecone、Qdrant、Redis、Replicate、Requests、SQLAlchemy、Transformers、VertexAI、WatsonX、Weaviate。默认集成在H.__init__末尾自动实例化并enable()通过disabled_integrations参数可按INTEGRATION_KEY排除。值得注意的源码细节是Django、Flask、FastAPI 并不在默认集成列表中——它们属于框架级集成必须在H(project_id, integrations[...])中显式传入。原因从实现可见这三个集成需要包装框架自身的 WSGI/请求入口WSGIHandler.__call__、Flask.__call__、Starlette 中间件属于对框架主流程的侵入式改造由用户按需显式启用更安全。结语从 README.md 这份精炼的开发者指南出发可以看到 highlight-io Python SDK 的完整开发闭环Poetry 安装依赖 → 在 Django/Flask/FastAPI/Loguru 四个 e2e 示例中本地验证 → 用pytest跑全量集成测试 → 用black统一风格。而深入到 sdk.py 与integrations目录又能理解其OpenTelemetry 发行版的架构本质H类统一初始化 Trace/Logs/Metrics 三条 OTLP 导出链路X-Highlight-Request头把后端错误/日志/追踪与前端会话回放精确关联Integration抽象层则让 20 余个第三方库可以一行配置即完成自动插桩。对于希望参与 SDK 开发或自建本地联调环境的开发者按本文步骤即可快速上手。赞分享可观测性后端【免费下载链接】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点击查看免费下载相关推荐RisingWave Iceberg E2E 测试指南本地运行、测试用例编写与 CI 集成RisingWave Iceberg E2E 测试指南本地运行、测试用例编写与 CI 集成 本文围绕 RisingWave 仓库中 e2e_test/iceb数据库流处理后端数据工程Builder.io SDK 开发实战Nx Mitosis 驱动的多框架 SDK 构建、集成测试与本地联调指南Builder.io SDK 开发实战Nx Mitosis 驱动的多框架 SDK 构建、集成测试与本地联调指南 Builder.io SDK 采用 wr前端低代码CMShighlight E2E 示例应用用 docker compose 与 app_runner 验证全栈 SDK 数据采集highlight E2E 示例应用用 docker compose 与 app_runner 验证全栈 SDK 数据采集 本文介绍 highlight.io可观测性后端上一篇逆向工程终极指南5分钟掌握Wallpaper Engine资源提取与转换下一篇2026终极指南JetBrains IDE试用期重置插件一键恢复30天免费使用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考