1. 项目概述当AI Agent遇上可观测性我们到底缺了什么最近和几个做AI应用落地的朋友聊天大家普遍有个头疼的问题自家的AI Agent智能体上线后一旦出点幺蛾子排查起来简直像在“开盲盒”。你只知道最终结果不对比如用户问“帮我订一张明天去上海的机票”Agent却返回了一堆天气信息。但中间到底发生了什么是意图识别错了还是调用工具链时参数传歪了又或者是大模型本身“胡言乱语”现有的监控日志往往只能告诉你“调用了A接口耗时XX毫秒返回了错误码500”至于这个错误码背后是Agent的“思考过程”出了偏差还是外部API服务挂了根本无从得知。这就是当前AI Agent可观测性体系面临的核心困境——语义空白。传统的可观测性三大支柱指标、日志、链路追踪在应对确定性的、流程驱动的微服务时游刃有余但面对AI Agent这种具有非确定性、复杂推理链路的“黑盒”时就有点力不从心了。我们能看到“点”单个调用和“线”简单的HTTP调用链却看不清Agent内部完整的“决策图谱”和“思维脉络”。而龙蜥社区的LoongSuite最近提出的基于OpenTelemetryOTel扩展规范来填补这一空白的思路恰好戳中了这个痛点。这不仅仅是加几个埋点那么简单它关乎我们能否真正理解、信任并有效治理这些日益复杂的AI智能体。简单来说这个项目要解决的是如何给AI Agent的每一次“思考”和“行动”加上可理解的、标准化的“注释”让开发者和运维人员能够像调试传统代码一样清晰地透视Agent内部的决策逻辑、工具使用情况、与大模型的交互细节以及资源消耗从而快速定位问题、评估效果并持续优化。接下来我会结合LoongSuite的思路拆解如何一步步构建起这套语义完整的AI Agent可观测体系。2. 核心困境解析为什么传统可观测性在AI Agent面前失灵了在深入方案之前我们必须先搞清楚面对AI Agent传统的监控手段到底“失灵”在哪儿。只有理解了问题本质才能明白后续每一个设计决策的意义。2.1 AI Agent运行范式的根本性转变传统的微服务或单体应用其执行路径是相对确定的。给定输入和代码输出在绝大多数情况下是可预期的执行流程也遵循预设的控制流。因此链路追踪Tracing可以清晰地描绘出服务间的调用关系日志可以记录关键的执行状态指标可以统计吞吐量和延迟。但AI Agent的运行范式发生了根本性变化非确定性同样的问题大模型可能会生成不同的回答Agent根据上下文可能选择不同的工具或执行路径。这使得“标准”的链路变得模糊。长周期、多步骤完成一个用户任务如规划旅行可能需要多次调用大模型进行思考Reasoning、多次调用外部工具如搜索、订票API、并在多次循环中保持记忆Memory。这是一个动态生成的、树状或图状的执行图谱而非线性的调用链。富语义的中间状态Agent的核心价值在于其“思考过程”。这包括了它对用户意图的理解Intent、拆解出的子任务Sub-task、每一步的推理内容Chain-of-Thought、对工具的选择和参数化Tool Calling、以及从工具或记忆中获取的信息Context。这些状态包含了丰富的业务和逻辑语义但传统Span通常只记录“调用了什么”和“耗时多久”丢失了“为什么这么调用”和“调用时想了什么”这些关键信息。2.2 现有可观测性数据的“语义断层”基于以上特点当我们仅用传统的OTel Span来追踪一个AI Agent时会遇到严重的“语义断层”Span名称空洞化你可能会看到一连串名为llm.invoke、tool.execute的Span。它们能告诉你Agent调了10次大模型、5次工具但完全无法回答“这10次调用分别是为了解决什么问题”、“这5个工具调用之间的逻辑关系是什么”。属性Attributes信息过载与无序开发者可能会把大量信息如完整的用户提问、模型回复、工具参数等以Key-Value形式塞进Span的Attributes里。这虽然保留了数据但缺乏结构。当你想分析“Agent在哪种类型的子任务上最常出错”时需要从杂乱无章的Attributes中手动解析和归类效率极低且难以标准化。链路Trace无法体现决策逻辑一个Trace可能显示了Span的父子关系和时序但无法直观体现这是Agent在执行“规划-执行-反思”循环中的哪一步。两个逻辑完全不同的任务如写邮件和查数据可能产生拓扑结构相似的Trace让人无法快速区分。举个具体例子用户请求“总结今天关于OpenAI最新模型的热点新闻”。一个理想的Agent可观测性视图应该能告诉我们Agent首先理解了用户意图是“总结新闻”。它拆解出子任务a) 搜索今日新闻b) 筛选与OpenAI相关的内容c) 进行总结。在执行子任务a时它先尝试调用“搜索引擎A”但返回结果为空于是它 fallback 到“搜索引擎B”并成功。在筛选内容时它调用了一次大模型来判断文章相关性。最终它将筛选后的文章列表交给大模型生成总结。而传统追踪可能只给你看llm.invoke-tool.execute (search_A)-tool.execute (search_B)-llm.invoke-llm.invoke。中间的意图、任务拆解、决策逻辑为什么从A切到B、业务实体“OpenAI”、“热点新闻”这些核心语义全部丢失了。3. LoongSuite OTel扩展规范的核心设计思想LoongSuite的方案没有另起炉灶而是选择在云原生可观测性的事实标准——OpenTelemetryOTel框架内进行扩展。这是一个非常务实且具有前瞻性的选择保证了方案的兼容性和生态活力。其核心思想可以概括为“分层注入语义规范定义内涵”。3.1 利用OTel的扩展能力Semantic Conventions与Span EventsOTel本身提供了强大的扩展能力LoongSuite的方案主要基于两个特性进行深化语义约定Semantic Conventions的定制化OTel定义了许多“语义约定”比如http.method、db.operation用来标准化特定领域Span的属性Attributes和事件Events。LoongSuite的思路是为AI Agent领域定义一套新的、细化的语义约定。这不仅仅是定义几个新的Attribute Key更是定义一套结构化的数据模型来描述Agent的各个组件和行为。Span事件Span Events的语义化使用Span Events代表Span生命周期内的“时刻”传统上用于记录日志Logs。LoongSuite将其提升为承载关键语义事件的载体。例如Agent内部产生一个“子任务规划完成”的事件或大模型生成了一段“推理过程Chain-of-Thought”这些都可以作为具有特定语义的Event附加到相应的Span上从而在时间线上标记出重要的逻辑节点。3.2 核心语义模型为Agent的“思维”建模这是整个方案最精髓的部分。LoongSuite试图通过扩展规范标准化描述Agent内部的核心概念及其关系我将其理解为以下几个关键模型会话Session与回合Turn模型一个用户对话会话Session包含多个交互回合Turn。每个Turn对应一次用户输入和Agent的完整响应周期。这层模型将零散的Span组织到有业务意义的上下文中。工作流Workflow与步骤Step模型在一个Turn内Agent为完成任务所执行的一系列逻辑步骤。例如可能遵循ReActReasoning-Acting模式思考(Reason) - 行动(Act) - 观察(Observe) - 再思考... 每一步Step都可以映射为一个或多个Span并通过Attributes标明其类型如agent.step.typereasoning。工具调用Tool Call的增强模型不仅记录调用了哪个工具tool.name还要结构化地记录调用意图tool.call.purpose、输入参数的生成过程关联到前一个推理Span的ID、以及工具返回结果的结构化摘要例如从返回的JSON中提取出flight.numberCA1234而不是一股脑塞进一个长的字符串属性里。大模型交互的增强模型除了记录模型名称、token消耗等基础信息关键是要关联本次调用的“提示词Prompt模板ID”和“主要输入变量”如用户问题、上下文摘要。这样当发现某类问题总是出现在使用某个特定Prompt模板时就能快速定位优化方向。意图Intent与实体Entity的附着在会话或回合层面记录识别出的用户意图如intentbook_flight和关键实体如entity.destination上海,entity.date2023-10-27。这些信息可以作为Trace或Span的顶级属性为后续的检索和分析提供强大的语义过滤条件。通过这套模型我们理想中的那个“总结新闻”的Agent追踪就会变成Trace具有属性agent.session.idxxx,agent.turn.idyyy,agent.intentsummarize_news,agent.entities[OpenAI, today]。Trace内部包含一个agent.workflowSpan其子Span通过agent.step.type明确标注为planning,retrieval,filtering,summarization。retrieval步骤下的tool.executeSpan会明确记录tool.call.purposesearch_news并且其失败和后续重试的Span通过agent.retry.attempt属性关联起来。filtering步骤下的llm.invokeSpan会通过一个Span Event记录下模型用于判断相关性的关键推理文本。这样一个富含语义的、可查询、可分析的执行图谱就生成了。4. 实操基于扩展规范构建Agent可观测体系理论说再多不如看看具体怎么落地。下面我以一个基于LangChain或LlamaIndex构建的、具备工具调用能力的AI Agent为例拆解如何一步步植入这套可观测性规范。4.1 第一步定义并集成语义约定库首先你需要将LoongSuite提出的扩展语义约定假设它们以某种形式发布如一个Python包opentelemetry-semantic-conventions-agent集成到你的项目中。# 假设性的安装命令 pip install opentelemetry-semantic-conventions-agent然后在你的OTel初始化代码中你需要确保这些约定能被识别。更重要的是你要在Agent框架的关键扩展点使用这些约定来丰富Span和Event。例如在LangChain中你可以通过自定义Callback或Instrumentor来实现from opentelemetry import trace from opentelemetry.semconv import agent # 假设的导入方式 import langchain from langchain.callbacks.base import BaseCallbackHandler class SemanticAwareCallbackHandler(BaseCallbackHandler): def on_chain_start(self, serialized, inputs, **kwargs): tracer trace.get_tracer(__name__) span_name fagent.chain.{serialized.get(name, unknown)} with tracer.start_as_current_span(span_name) as span: # 设置工作流/步骤类型 if planning in span_name: span.set_attribute(agent.AGENT_STEP_TYPE, planning) elif retrieval in span_name: span.set_attribute(agent.AGENT_STEP_TYPE, retrieval) # 将当前span存储到上下文中供后续步骤使用 context trace.set_span_in_context(span) kwargs[run_id].span_context context def on_llm_start(self, serialized, prompts, **kwargs): parent_span trace.get_current_span() if parent_span.is_recording(): # 记录LLM调用的增强语义 parent_span.set_attribute(agent.LLM_PROMPT_TEMPLATE_ID, summary_system_v2) # 可以将核心输入变量也作为属性注意隐私过滤 main_input prompts[0][:100] # 示例截取部分 parent_span.set_attribute(agent.LLM_MAIN_INPUT, main_input) def on_tool_start(self, serialized, input_str, **kwargs): tool_name serialized.get(name) with trace.get_tracer(__name__).start_as_current_span(ftool.{tool_name}, contextkwargs[run_id].span_context) as span: span.set_attribute(agent.TOOL_NAME, tool_name) # 解析input_str尝试提取结构化目的 # 例如从输入JSON中解析出指令 try: input_dict json.loads(input_str) purpose input_dict.get(action, unknown) span.set_attribute(agent.TOOL_CALL_PURPOSE, purpose) except: span.set_attribute(agent.TOOL_CALL_PURPOSE, execute) # 记录关键输入参数脱敏后 span.set_attribute(agent.TOOL_INPUT_PARAMS, self._sanitize_input(input_str))关键操作解析识别扩展点在Agent框架的各个生命周期事件链开始、LLM调用开始、工具调用开始等处插入代码。设置语义属性使用扩展的语义约定如agent.AGENT_STEP_TYPE,agent.TOOL_CALL_PURPOSE来为Span打上富含业务意义的标签而不是简单的nametool_execute。维护上下文确保相关的Span能通过OTel的Context机制关联起来形成正确的父子关系从而构建出有逻辑的Trace。4.2 第二步在关键决策点记录Span EventsSpan Events非常适合记录那些不改变主流程状态但具有重要诊断意义的“瞬间”。对于AI Agent以下事件至关重要意图识别结果当NLU模块识别出用户意图时。任务规划输出当Planner模块输出任务分解树时。关键推理步骤Chain-of-Thought当大模型生成重要的中间推理文本时。工具执行结果摘要当工具返回大量数据时记录一个结构化摘要如“查询到3条航班信息最低价格1200元”而非全部原始数据。异常与重试当发生错误、触发重试或降级策略时。def on_llm_end(self, response, **kwargs): parent_span trace.get_current_span() if parent_span.is_recording(): # 检查LLM输出中是否包含推理链CoT if hasattr(response, generations): for gen in response.generations: text gen.text # 简单示例通过关键词或特定格式判断是否为推理步骤 if 因此 in text or 因为 in text or 步骤 in text: # 记录为Span Event parent_span.add_event(nameagent.reasoning.chain_of_thought, attributes{ agent.reasoning.step: text[:200] # 截取部分 })注意事项事件命名规范化事件名称也应遵循约定如agent.reasoning.chain_of_thought便于后续统一分析。数据量控制Event中携带的数据应是摘要性的、结构化的避免记录过长的原始文本以免造成传输和存储的压力。隐私与安全务必对可能包含用户隐私或敏感信息的事件内容进行脱敏处理。4.3 第三步在Trace层面注入会话与意图语义单个Span的语义再丰富也需要在更高维度进行组织。这通常在处理一个用户请求的最初入口处完成。from opentelemetry import baggage from opentelemetry.semconv import agent app.post(/chat) async def chat_endpoint(request: ChatRequest): tracer trace.get_tracer(__name__) # 1. 提取或生成会话、回合ID session_id request.session_id or str(uuid.uuid4()) turn_id str(uuid.uuid4()) # 2. 创建代表整个对话回合的根Span with tracer.start_as_current_span(agent.turn) as root_span: # 3. 在Trace层面设置会话和回合属性 root_span.set_attribute(agent.AGENT_SESSION_ID, session_id) root_span.set_attribute(agent.AGENT_TURN_ID, turn_id) # 4. 可选调用NLU服务识别意图和实体并记录到Trace intent, entities await nlu_service.analyze(request.message) root_span.set_attribute(agent.AGENT_INTENT, intent) if entities: # 实体可以记录为JSON字符串或多个属性 root_span.set_attribute(agent.AGENT_ENTITIES, json.dumps(entities)) # 5. 将关键信息放入Baggage在整个Trace上下文中传播 # 这样后续所有深层次的Span都能方便地获取这些信息 ctx baggage.set_baggage(agent.intent, intent, contexttrace.set_span_in_context(root_span)) # 6. 在增强后的上下文中执行Agent核心逻辑 with trace.use_span(root_span, end_on_exitFalse): response await agent_executor.ainvoke( {input: request.message}, config{callbacks: [SemanticAwareCallbackHandler()], run_name: fturn-{turn_id}}, contextctx # 传递上下文 ) root_span.end() return response设计考量入口即治理在请求入口处就建立完整的可观测性上下文确保整个调用链都在监控之下。语义上行将高层业务语义意图、实体从源头注入并利用OTel的Baggage机制向下游传播使得任何一个底层Span在需要时都能访问到这些信息便于关联分析。Trace作为分析单元这样配置后每一个完整的用户交互Turn都会对应一个独立的Trace。我们可以直接通过意图agent.intentbook_flight或实体agent.entities:destination上海来检索和聚合相关的Trace进行业务层面的性能、质量分析。5. 数据消费与治理让语义数据产生价值采集了富含语义的可观测性数据只是第一步如何消费和分析这些数据将其转化为治理能力才是最终目标。这里涉及到数据导出、存储、查询和可视化。5.1 后端配置与数据导出你需要配置OTel Collector接收来自Agent应用的数据并进行可能的处理如属性过滤、采样后导出到后端系统。# otel-collector-config.yaml 示例 receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: # 1. 资源检测为所有数据添加服务名、实例等信息 resource: attributes: - key: service.name value: ai-customer-service-agent action: upsert # 2. 批量处理优化性能 batch: timeout: 1s send_batch_size: 512 # 3. 可选基于语义的属性过滤采样 probabilistic_sampler: sampling_percentage: 100 # 全量采集或根据agent.intent等关键属性设计采样策略 exporters: # 导出到Jaeger进行链路追踪查看 jaeger: endpoint: jaeger:14250 tls: insecure: true # 导出到Prometheus兼容的端点用于生成指标 prometheus: endpoint: 0.0.0.0:8889 # 导出到Loki进行日志/事件检索Span Events可以作为日志处理 loki: endpoint: http://loki:3100/loki/api/v1/push labels: attributes: - agent.intent - agent.session.id - service.name # 导出到Elasticsearch进行更灵活的Trace和明细数据检索与分析 elasticsearch/traces: endpoints: [http://elasticsearch:9200] traces_index: otel-traces tls: insecure: true service: pipelines: traces: receivers: [otlp] processors: [resource, batch] exporters: [jaeger, elasticsearch/traces] metrics: receivers: [otlp] processors: [resource, batch] exporters: [prometheus] logs: # 将Span Events作为日志处理 receivers: [otlp] processors: [resource, batch] exporters: [loki]关键点多后端导出将数据导出到适合不同用途的后端。Jaeger用于查看单条链路详情Elasticsearch用于复杂的跨Trace聚合查询Loki用于检索Span Events中的文本信息如推理链Prometheus用于监控关键指标。利用语义标签在导出到Loki或配置Elasticsearch索引时可以利用我们注入的语义属性如agent.intent作为标签Label或索引字段。这是将数据“激活”的关键一步使得后续能按业务维度进行高效过滤和聚合。5.2 核心监控指标与告警定义基于语义化的数据我们可以定义出远比“错误率”、“延迟”更有洞察力的业务和技术指标。技术健康度指标agent_llm_call_duration_seconds{modelgpt-4, intentbook_flight}按意图和模型分类的LLM调用耗时。agent_tool_call_failure_rate{toolflight_search_api, purposesearch_one_way}按工具和调用目的分类的失败率。agent_step_duration_seconds{step_typereasoning}各类步骤推理、检索等的耗时分布。业务质量与效果指标agent_intent_recognition_accuracy意图识别准确率需要结合标注数据计算。agent_task_completion_rate{intentcomplex_booking}复杂任务的完成率需要定义“完成”的判定逻辑。agent_llm_retry_count{reasoncontext_length_exceeded}因上下文过长触发重试/总结的次数。告警示例# Prometheus Alertmanager 配置示例 - alert: HighFailureRateForFlightSearch expr: rate(agent_tool_call_failure_rate{toolflight_search_api}[5m]) 0.1 for: 2m labels: severity: critical domain: ai-agent annotations: summary: 航班搜索工具调用失败率过高 (实例 {{ $labels.instance }}) description: 航班搜索API在过去5分钟失败率超过10%当前值为 {{ $value }}。可能影响机票预订流程。关联意图{{ with query \agent_tool_call_failure_rate{toolflight_search_api}\ }}{{ . | label \agent.intent\ }}{{ end }}注意告警描述中我们尝试关联了agent.intent标签这能帮助运维人员快速理解影响的业务范围。5.3 基于语义的查询、分析与可视化当数据存储到位后强大的查询能力就得以释放。在Elasticsearch中分析特定意图的链路瓶颈GET otel-traces/_search { query: { bool: { filter: [ { term: { resource.attributes.agent.intent: book_flight } }, { range: { duration: { gte: 10000 } } } // 查找耗时大于10秒的慢Trace ] } }, aggs: { slow_step_breakdown: { terms: { field: spans.attributes.agent.step.type }, // 按步骤类型聚合 aggs: { avg_duration: { avg: { field: spans.duration } } } } } }这个查询能直接告诉我们在“订机票”这个意图下慢请求主要卡在哪个类型的步骤是reasoning思考太久还是tool_execution调用外部API慢。在Grafana中构建业务视角的仪表盘全局概览展示各意图的请求量、平均耗时、成功率热力图。深度分析针对某个特定意图如“总结新闻”下钻查看其下各类步骤规划、检索、筛选、总结的耗时占比、工具调用成功率、LLM的Token消耗分布。问题排查当用户反馈某个回答不准时可以通过session.id或turn.id直接定位到该次交互的完整Trace在Jaeger UI上逐层展开查看每一步的输入、输出、推理过程和工具调用详情精准复现问题现场。实操心得指标设计要迭代不要试图一开始就定义完美的指标集。先基于扩展规范采集全量的语义化Trace数据。在运营过程中根据常遇到的问题如“用户总说订票结果不对”反向推导需要聚合和监控什么指标然后逐步在Grafana中创建对应的图表和告警。可视化服务于场景为不同角色设计不同的Dashboard。给产品经理看的可能是“各意图任务完成率”和“用户满意度如有”给AI工程师看的是“提示词模板效果对比”和“模型输出稳定性”给运维看的是“服务健康度”和“资源消耗”。语义化的数据让这种定制化成为可能。6. 常见问题与避坑指南在实际落地过程中我遇到并总结了一些典型问题和解决方案。6.1 性能开销与采样策略问题为每个LLM调用、工具调用都记录详细的属性、事件会不会带来不可接受的性能开销延迟增长、资源消耗解决方案异步上报确保OTel SDK配置为异步模式导出数据避免阻塞主业务线程。精细化采样不要全量采集。利用OTel的头部采样Head Sampling和尾部采样Tail Sampling。头部采样在Trace开始时决定是否采样。可以基于agent.intent进行决策例如对核心业务意图如支付、预订进行100%采样对闲聊类意图进行1%采样。尾部采样在Collector端根据Trace的最终结果或特征决定是否保留。例如只保留包含错误、或耗时超过阈值的Trace以及随机保留一部分成功Trace用于基线分析。# OTel Collector 尾部采样处理器配置示例 processors: tail_sampling: decision_wait: 10s # 等待一段时间再做决定以便获取Trace完整状态 policies: - name: keep-errors type: status_code status_code: {status_codes: [ERROR]} - name: keep-slow-traces type: latency latency: {threshold_ms: 5000} - name: random-sample-for-intent type: probabilistic probabilistic: {sampling_percentage: 10} # 可以结合attribute过滤例如只对特定意图采样属性精简避免在Span Attributes中记录过大的数据如完整的Prompt或响应。使用Event记录关键摘要并将原始大数据存储到专门的日志或对象存储中仅在Attributes里保留一个引用ID。6.2 数据隐私与安全合规问题用户与AI的对话可能包含高度敏感信息PII如何确保可观测性数据不泄露隐私解决方案客户端脱敏在SDK端集成脱敏处理器。在将数据放入Span Attributes或Events之前对可能包含PII姓名、电话、身份证号、邮箱的字段进行识别和掩码处理如替换为[REDACTED]或哈希值。class PIIRedactionProcessor: def process(self, attributes): redacted_attrs {} for k, v in attributes.items(): if isinstance(v, str): # 使用正则或专业库识别PII if self._contains_pii(v): redacted_attrs[k] self._redact_pii(v) else: redacted_attrs[k] v else: redacted_attrs[k] v return redacted_attrs服务端过滤在OTel Collector中配置属性过滤器attributes处理器强制删除或覆盖某些敏感字段。访问控制确保存储可观测性数据的后端系统如ES、Jaeger有严格的权限控制只有授权的运维和研发人员才能访问原始Trace数据。数据保留策略制定并执行严格的数据保留周期定期自动删除过期数据。6.3 与现有Agent框架的融合复杂度问题LangChain、LlamaIndex等框架结构复杂如何无侵入或低侵入地接入解决方案优先使用框架提供的回调或Instrumentor机制如LangChain的BaseCallbackHandlerLlamaIndex的CallbackManager。这是最标准、侵入性最低的方式。我们的SemanticAwareCallbackHandler示例就是基于此。创建自定义Instrumentor如果回调机制不能满足所有埋点需求例如需要更底层地拦截框架内部调用可以模仿OTel社区为其他库如opentelemetry-instrumentation-requests的做法创建自定义的Instrumentor。这需要深入理解框架源码工作量较大但可以实现最全面的覆盖。装饰器模式对于自己封装的核心函数如工具调用函数、LLM调用函数可以使用OTel的装饰器自动创建Span。from opentelemetry import trace from opentelemetry.trace import Status, StatusCode tracer trace.get_tracer(__name__) tracer.start_as_current_span(my_custom_tool) def call_custom_tool(params): span trace.get_current_span() try: span.set_attribute(agent.tool.name, my_tool) span.set_attribute(agent.tool.call.purpose, params.get(purpose)) # ... 实际调用逻辑 return result except Exception as e: span.set_status(Status(StatusCode.ERROR)) span.record_exception(e) raise保持轻量逐步覆盖不要强求一次性覆盖所有场景。先从最核心、最易出问题的环节开始如工具调用、最终LLM输出逐步扩大覆盖范围。优先保证关键路径的语义完整性。6.4 语义约定的维护与演进问题自定义的语义约定如agent.step.type的枚举值如何在不同团队、不同服务之间保持一致并演进解决方案内部“契约”将你们团队定义的语义约定整理成一份正式的文档或Protobuf/JSON Schema文件作为团队内部的“可观测性契约”。共享代码库创建内部Python包如company-telemetry-agent-conventions包含所有常量和工具函数。所有服务强制依赖此包来设置属性确保Key和Value的定义一致。版本化与兼容性当约定需要变更时如新增一个step.type采用向后兼容的方式。新代码开始使用新值但旧代码和查询语句在一段时间内继续有效。在Collector端可以配置处理器将旧值映射为新值或同时写入新旧两个值。向社区靠拢积极关注LoongSuite等社区项目的进展。如果它们的规范成熟并被广泛接受应优先考虑迁移到社区标准以减少长期维护成本并提升互操作性。在过渡期可以在Collector中做一次性的属性转换。
