ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Litestar OpenTelemetry 插件完全指南:从安装接入到 OpenTelemetryConfig 全参数深度解析

Litestar OpenTelemetry 插件完全指南:从安装接入到 OpenTelemetryConfig 全参数深度解析 Litestar OpenTelemetry 插件完全指南从安装接入到 OpenTelemetryConfig 全参数深度解析【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar本篇指南围绕 Litestar 内置的 OpenTelemetry 集成litestar.plugins.opentelemetry展开从依赖安装、插件接入方式到OpenTelemetryConfig全部配置参数的逐项解析并结合仓库源码与单元测试讲清该插件在 ASGI 层生成 Span / Metrics 的实际工作机制帮助你在生产 Litestar 应用中快速落地可观测性链路追踪 指标采集。一、依赖安装OpenTelemetry 支持在 Litestar 中属于可选依赖不是核心包的一部分。文档docs/usage/metrics/opentelemetry.rst给出了两种安装方式任选其一# 方式一单独安装 ASGI 插桩包 pip install opentelemetry-instrumentation-asgi# 方式二作为 Litestar extra 安装 pip install litestar[opentelemetry]这一「可选依赖」的设计在源码中体现得很直接OpenTelemetryConfig、OpenTelemetryInstrumentationMiddleware等模块在导入时会先探测opentelemetry是否可用若未安装则抛出MissingDependencyException(opentelemetry)例如 config.py 和 middleware.py 开头的try/except ImportError逻辑。这意味着你可以按需在子模块中延迟导入该插件而不影响未启用可观测性的环境。二、接入方式OpenTelemetryPlugin OpenTelemetryConfig官方文档给出的最小可用接入方式如下from litestar import Litestar from litestar.plugins.opentelemetry import OpenTelemetryConfig, OpenTelemetryPlugin open_telemetry_config OpenTelemetryConfig() app Litestar(plugins[OpenTelemetryPlugin(open_telemetry_config)])三个核心入口类均在init.py 中导出类文件职责OpenTelemetryConfigconfig.pydataclass 配置对象承载全部插桩参数OpenTelemetryInstrumentationMiddlewaremiddleware.pyASGI 中间件内部包装官方OpenTelemetryMiddlewareOpenTelemetryPluginplugin.pyInitPlugin实现把中间件注册进应用2.1 插件的工作机制OpenTelemetryPlugin继承自 Litestar 的InitPlugin见 plugin.py其生命周期由两个关键点构成middleware属性懒加载生成DefineMiddleware(OpenTelemetryInstrumentationMiddleware, configself.config)。Litestar 应用初始化时会读取插件的middleware属性将其加入中间件栈on_app_init钩子若配置了after_exception_hook_handler插件会把它追加到app_config.after_exception列表中使异常钩子在全局异常处理链中生效。同时它调用_pop_otel_middleware从已有中间件列表中移除重复的 OTEL 中间件实例避免用户既手动传middleware[config.middleware]又通过插件注册时产生双重插桩。单元测试用参数化 fixture 同时验证了「直接注册中间件」与「通过插件注册」两条路径行为一致test_opentelemetry.pypytest.fixture(params[middleware, plugin]) def app_config(request, config) - AppConfig: if request.param middleware: return AppConfig(middleware[config.middleware]) return AppConfig(plugins[OpenTelemetryPlugin(config)])2.2 Provider 配置开箱即用与显式注入两种模式文档明确指出上述最小示例在「已配置全局tracer_provider/meter_provider和对应 Exporter」的前提下即可开箱工作。若希望显式控制也可以把 Provider 直接传给OpenTelemetryConfig。仓库的测试用例完整演示了显式注入的写法——构建带Resource、InMemorySpanExporter的TracerProvider再加上带InMemoryMetricReader的MeterProviderfrom opentelemetry.sdk.resources import SERVICE_NAME, Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import SimpleSpanProcessor from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter from opentelemetry.metrics import get_meter_provider exporter InMemorySpanExporter() tracer_provider TracerProvider(resourceResource(attributes{SERVICE_NAME: litestar-test})) tracer_provider.add_span_processor(SimpleSpanProcessor(exporter)) meter get_meter_provider().get_meter(litestar-test) config OpenTelemetryConfig(tracer_providertracer_provider, metermeter)见 test_opentelemetry.py 的configfixture生产环境中把InMemorySpanExporter替换为实际的 OTLP 等 Exporter 即可。三、OpenTelemetryConfig 全参数详解OpenTelemetryConfig是一个 dataclassconfig.py下面按功能分组完整解析每个字段的默认值与作用。3.1 Provider 相关决定数据往哪写参数类型默认值说明tracer_providerTracerProvider \| NoneNone使用的追踪 Provider缺省时回退到全局配置的tracer_providermeter_providerMeterProvider \| NoneNone使用的指标 Provider缺省时回退到全局配置tracerTracer \| NoneNone预构建的 Tracer 实例缺省时由tracer_provider创建meterMeter \| NoneNone预构建的 Meter 实例缺省时用meter_provider或全局创建3.2 钩子回调在关键路径上挂自定义逻辑参数签名触发时机server_request_hook_handlerCallable[[Span, dict[str, Any]], None]每个入站请求到达时收到 server span 与 ASGI scopeclient_request_hook_handlerCallable[[Span, dict, dict], None]ASGIreceive被调用时收到内部 span、scope 与 ASGI 消息client_response_hook_handlerCallable[[Span, dict, dict], None]ASGIsend被调用时收到内部 span、scope 与 ASGI 消息after_exception_hook_handlerAfterExceptionHookHandler \| None任何异常抛出时收到异常对象与 scope 对象源码中的类型别名明确了各钩子的参数约定config.py。这里有一个值得注意的细节client_request_hook/client_response_hook接收3 个参数span、scope、message而server_request_hook只有2 个参数span、scope——测试用例test_client_request_hook_receives_three_params、test_server_request_hook_receives_two_paramstest_opentelemetry.py专门回归验证了这一点。client_request_hook只在发生receive()即读取请求体如 POST时触发。after_exception_hook_handler的行为由测试验证仅当请求抛出异常时触发一次成功请求不触发并且通过OpenTelemetryPlugin.on_app_init自动挂入应用的after_exception链见 plugin.py 与 test_opentelemetry.py。3.3 Span 命名与属性参数默认值说明scope_span_details_extractorget_route_details_from_scope回调返回(span_name, extra_attributes)定义默认 Span 名称与附加属性默认提取器get_route_details_from_scope_utils.py的逻辑HTTP 请求scope 中同时有method和pathSpan 名为METHOD /path如GET /users并附加HTTP_ROUTE: METHOD /path属性WebSocket无 methodSpan 名为pathHTTP_ROUTE属性为path。从源码结构看将http.route设为路由模板而非具体 URL有利于指标按路由聚合避免高基数大量不同 URL 参数导致 Span/Metrics 数量爆炸。你可以在测试中确认最终落地的属性集合test_opentelemetry.pyHTTP 请求会生成包含http.scheme、http.method、http.url、http.route、http.status_code、net.host.port等在内的完整 Span 属性。3.4 URL 排除与过滤参数默认值说明excludeNone字符串或字符串列表形式的匹配模式命中的 URL 将被跳过插桩exclude_opt_keyNone用于在路由上标记「跳过插桩」的标识键route opt keyexclude_urls_env_keyLITESTAR环境变量前缀形如LITESTAR_EXCLUDED_URLS的环境变量可传入排除的 URL 列表exclude_spansNonelist[Literal[receive, send]]可从 Trace 中排除 HTTPreceive和/或send产生的 Span其中环境变量排除机制在 middleware.py 中通过get_excluded_urls(config.exclude_urls_env_key)接入上游opentelemetry.util.http的工具函数。测试test_exclude_opt_key_no_keyerror_without_route_handlertest_opentelemetry.py还验证了设置exclude_opt_key后即使 OTEL 中间件位于最外层此时scope[route_handler]尚未被路由填充也不会抛出KeyError。3.5 请求头采集与脱敏参数说明http_capture_headers_server_requestlist[str] \| None要采集为 Span 属性的请求头名称列表http_capture_headers_server_responselist[str] \| None要采集为 Span 属性的响应头名称列表http_capture_headers_sanitize_fieldslist[str] \| None这些头字段的值会在 Span 属性中被替换为[REDACTED]用于authorization、cookie等敏感头测试用例test_new_config_params_acceptedtest_opentelemetry.py展示了典型配置config OpenTelemetryConfig( http_capture_headers_server_request[content-type, x-request-id], http_capture_headers_server_response[content-type], http_capture_headers_sanitize_fields[authorization, cookie], )3.6 作用范围与中间件替换参数默认值说明scopesNone中间件处理的 ASGI scope 类型缺省时http与websocket都会处理middleware_classOpenTelemetryInstrumentationMiddleware使用的中间件类应为OpenTelemetryInstrumentationMiddleware的子类便于继承覆写middleware_class与scopes/exclude/exclude_opt_key会一并传入AbstractMiddleware基类middleware.py从而获得 Litestar 原生的「按 scope 过滤 / 按 URL 排除 / 按 route opt key 排除」的中间件调度能力再叠加 OTEL 自身的排除机制。此外OpenTelemetryConfig还暴露了middleware属性config.py可直接DefineMiddleware(self.middleware_class, configself)生成中间件实例供不经过插件、手动加入middleware列表的场景使用。四、中间件内部官方 ASGI 插桩的包装层OpenTelemetryInstrumentationMiddlewaremiddleware.py自身很薄职责是「适配」构造时把OpenTelemetryConfig的字段一一映射到opentelemetry.instrumentation.asgi.OpenTelemetryMiddleware的官方参数client_request_hook、server_request_hook、default_span_details、excluded_urls、exclude_spans、meter、meter_provider、tracer_provider、tracer、三个 header 采集参数等ASGI__call__直接委托给内部self.open_telemetry_middleware(scope, receive, send)。这种包装让 Litestar 用户无需关心上游opentelemetry-instrumentation-asgi的 API 细节全部配置收敛到一个 dataclass 中同时保留middleware_class继承口子供深度定制。五、追踪覆盖范围HTTP、WebSocket 与错误场景单元测试test_opentelemetry.py覆盖了该插件的主要行为边界可作为验收依据HTTP 路由GET /成功请求产生三个 Span——http.response.start携带http.status_code: 200、http.response.body以及携带完整请求/路由/状态码属性的 server Span同时InMemoryMetricReader能取到指标数据说明 Metrics 通道也被打通test_opentelemetry.pyWebSocket 路由一次连接产生websocket.connect、websocket.accept、websocket.send、websocket.close四个内部 Span外加 server Spanhttp.scheme: ws、http.route: /test_opentelemetry.py404 / 405路由不存在或方法不允许时server Span 依然生成并正确记录http.status_code: 404/405证明错误响应也在追踪范围内test_opentelemetry.py中间件层抛出的异常在 OTEL 中间件内层的自定义中间件抛出NotAuthorizedException401时Span 属性中http.status_code仍为 401插桩不因上游异常而中断test_opentelemetry.py。六、与其他观测能力的关系Litestar 仓库的 metrics 文档目录docs/usage/metrics/index.rst下还包含 Prometheus 集成文档docs/usage/metrics/prometheus.rst。两者定位不同Prometheus 插件暴露/metrics拉取端点而 OpenTelemetry 插件走 Push 式导出Span/Metrics 通过你配置的 Exporter 发送到后端。从OpenTelemetryConfig的字段设计看它把「数据往哪写」完全交给标准 OTel Provider/Exporter 体系插件本身只负责在 ASGI 层正确插桩这一边界划分使得它可以与任意支持 OTLP 的可观测后端组合。小结安装opentelemetry-instrumentation-asgi或litestar[opentelemetry]extra后用Litestar(plugins[OpenTelemetryPlugin(OpenTelemetryConfig())])一行即可启用全部可调项集中在OpenTelemetryConfig这个 dataclassProvider 注入、四类钩子、Span 命名提取器、URL/环境级排除、请求头采集与脱敏、scope 过滤与中间件替换均支持显式配置默认行为对 HTTP 与 WebSocket 请求都生成带http.route、http.status_code等标准属性的 Span并在指标通道输出请求指标错误响应404/405/401/500同样被追踪需要更精细的控制时可继承OpenTelemetryInstrumentationMiddleware并通过middleware_class参数替换中间件实现相关测试可直接参考 tests/unit/test_plugins/test_opentelemetry.py。【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表