latitude-telemetry

Latitude Telemetry

添加或检查 Latitude Telemetry，同时不影响现有的可观测性。Latitude 基于 OpenTelemetry，因此应与应用现有的 OTel/Sentry/Datadog 配置组合使用，而不是将其替换。

入口

有两种入口；两者都执行相同的审查 → 插桩 → 验证流程：

• 直接调用——最常见的情况。用户已经拥有 Latitude 账户和 API 密钥，并希望为应用添加插桩：可以是该账户下的第一个项目，也可以是其他项目。用户可能已经知道项目 slug，也可以从代码库中推断，或通过 Latitude MCP/CLI 查找。按下文所述配置来源；不要运行零账户引导流程。
• 由 latitude-setup 委派——从零开始、没有账户的情况。该技能已配置临时账户，并将 LATITUDE_API_KEY/LATITUDE_PROJECT_SLUG 写入 .env，因此配置已就绪——跳过 MCP 查找步骤，直接开始审查 → 插桩。

无论哪种情况，只有验证真实跟踪记录已进入 Latitude（工作流第 6 步）后，工作才算完成。

首要决策：重定向现有 OTLP，还是添加 SDK？

安装任何内容前，先确定应用目前如何发出 Telemetry——最简单且正确的集成通常不需要添加新依赖：

• 应用已经导出 OpenTelemetry 跟踪记录——无论是通用 OTLP 导出器，还是 GenAI 插桩（如 Vercel AI SDK Telemetry（experimental_telemetry）、OpenInference、Traceloop/OpenLLMetry 或手动编写的 OTel span），都应优先将该导出器重定向到 Latitude，而不是安装 SDK。这只需更改配置——将 OTLP 跟踪记录端点设为 https://ingest.latitude.so/v1/traces，并添加身份验证和项目标头（见下文“其他目标 → 通用 OTLP”）。这会保留应用现有的 span 约定，且不会增加新的插桩。在此基础上安装 Latitude SDK 会对同一模型调用重复插桩，并可能造成 span 重复或覆盖——因此不要这样做，除非重定向无法传输你需要的数据。
• 应用尚无 LLM Telemetry（或只使用不导出 OTLP 的供应商 SDK）？请使用 Latitude SDK（下文的 TypeScript/Python 部分），或将 LatitudeSpanProcessor 附加到现有的 OTel 提供程序。

对于已经生成 span 的应用，重定向 OTLP 是风险更低的默认方案。请在审查期间确认适用情况，并在计划中说明所选方案。

工作流

1. 先进行审查

   • 确认语言、包管理器、入口点、运行时、部署配置和环境变量约定。
   • 在目标语言对应的包注册表中检查最新的 Latitude SDK；如果当前 alpha 版是最新发布版本，就使用它，不要照搬示例中的版本。
   • 检查是否存在 LATITUDE_API_KEY，以及 LATITUDE_PROJECT_SLUG 或按捕获路由项目的配置。检查环境变量文件、密钥管理器引用、部署配置、CI，以及用于目标运行环境的测试框架自身配置。如果缺少密钥，不要向用户索要。 缺少密钥表示以下两种情况之一，只有用户知道是哪一种：他们已有账号，可以提供密钥；或者他们还没有账号，应由 latitude-setup 立即创建一个临时账号（无需注册，之后再认领）。将此作为一个问题询问，并默认选择临时账号（见下文“还没有账号？”），然后继续。如果项目 slug、已启用的插件或依赖项旁边没有密钥，那只是占位符或遗留内容，并不能证明用户有账号。
   • 查找现有遥测：@opentelemetry/*、opentelemetry-*、dd-trace、@sentry/*、sentry-sdk、newrelic、Honeycomb、Jaeger/Tempo/OTLP 导出器、LangSmith/Langfuse/Helicone/Phoenix/Traceloop、自定义 span 处理器，以及 OTEL_* 环境变量。如果应用已经导出 OTLP，优先重定向现有导出，而不是安装 SDK（见上文“首要决策”）。否则，通常应先初始化现有 SDK；Latitude 随后初始化，或将 LatitudeSpanProcessor 挂载到现有 provider。
   • 查找 LLM 调用点：OpenAI chat/responses、Anthropic messages、Bedrock、Cohere、Together、Vertex/Google AI、Azure OpenAI、Vercel AI SDK generateText/streamText、LangChain、LlamaIndex、OpenAI Agents、LiteLLM、CrewAI 等。从路由/作业/CLI/Agent 入口点追踪到实际的模型调用。留意流式处理路径；应在捕获边界内消费流。
   • 记录应用是否保留长期记忆——即跨不同交互持久化并重新加载的状态（文件、数据库、向量存储、键值存储，或 Mem0/Zep/Supermemory 等提供方）；这不同于单次请求中的对话历史。如果有，强烈建议添加记忆可观测性——见下文“长期记忆？”。
   • 如果此处未明确涵盖用户需求，请查阅 Latitude 文档（https://docs.latitude.so/llms.txt，尤其是 telemetry/*），和/或 github.com/latitude-dev/latitude-llm/packages/telemetry/* 中的遥测包实现。

2. 归类用例

   • 按最终目标对相关提示词、工具、检索和模型调用进行分组，而不是按文件分组。
   • 对每组记录：入口点、LLM 调用、可用的用户/会话 ID、有用的标签/元数据、流式处理行为，以及项目路由。
   • 尽量在请求、作业或 Agent 轮次外包裹一个 capture()。只有在有实际意义的子边界处才添加嵌套捕获。

3. 规划前先澄清缺口

   • 只询问代码库无法回答的重要问题：轨迹应显示在 Latitude 的什么位置、谁负责补齐缺失的密钥/配置、现有可观测性是否必须保持不变、用例边界是否不明确，或是否批准大范围重构。
   • 假设用户不了解 Latitude SDK 或 OpenTelemetry。除非用户已表明具备相关专业知识，否则不要让他们在 SDK、处理器、导出器、环境变量方案、检测密钥或 OTLP 接线方式之间做选择。
   • 需要做出技术选择时，根据代码库推断最佳方案，用通俗语言说明对用户可见的结果和权衡，并征求确认。将实现细节留到计划中。
   • 按优先级一次只问一个问题，并在得到回答前暂停。绝不要将尚未解决的重要问题与征求批准合并提问。
   • 将低风险假设写入计划，而不是提问。

4. 先制定计划，再等待 解决所有重要的澄清事项后（包括 MCP 不可用时，初步确认是否安装/连接 Latitude MCP），简要列出计划，并等待用户明确批准，然后再安装软件包、编辑文件或更改配置。用通俗语言说明每项更改。批准必须明确无误（yes、approved、go ahead）。如果用户要求修改计划，或补充回答了先前遗漏的澄清问题，请修订计划并再次征求批准。不要在计划中包含尚未解决的澄清问题或可选的 MCP 设置提议；应在此步骤之前提出并解决这些问题。

   Plan
   - What Latitude will add: capture LLM requests/responses, token/model details, errors, latency, and user/session context where available.
   - Decisions/assumptions: ... (resolved clarifications, defaults chosen, and why they are safe)
   - Existing telemetry: ... (what is already present and whether it will be preserved)
   - LLM integrations found: ... (which model calls will be traced)
   - Capture boundaries: ... (which request/job/agent turn becomes one trace, and why)
   - Integration approach: ... (SDK bootstrap / existing OTel processor / generic OTLP, explained in plain language)
   - Env/config needed: ... (which values are needed, what they do, where to find them, and where placeholders/docs will be added)
   - Files to change: ... (what each file change accomplishes)
   - Verification: ... (which real flow will be run to emit traces, and how they'll be confirmed in Latitude — MCP, CLI, or API)
   
   Reply `go ahead` to approve this plan.
   

5. 仅在获得批准后实施

   • 不要将暗示或沉默视为批准；如果意图不明确，请询问。
   • 遵循现有的配置验证、模块布局、日志记录、测试和包管理模式。让锁文件记录解析后的 SDK 版本。
   • 将更改限定在遥测范围内：软件包、Latitude 初始化、采集边界、提供方遥测，以及环境变量示例/文档。对于大范围重构，必须另行获得明确许可，例如更改模块类型、切换构建系统、重新组织应用结构、替换遥测服务商、更改框架/运行时配置，或重写 LLM 抽象。
   • 切勿将真实密钥直接写入代码。使用环境变量或项目的密钥管理器。如果 Latitude MCP 工具可用，请使用它们确认/创建项目或密钥元数据；否则请询问缺失的密钥应由何处管理。
   • 尽可能在首次 LLM 调用之前，在启动时/模块作用域内初始化 Latitude 一次。避免为每个请求创建 SDK 实例。
   • 保留当前的可观测性；除非用户明确批准，否则不要移除 span 处理器/导出器。
   • 如果所需的配置或环境变量可能已经设置（例如 OTLP 端点/标头、LATITUDE_* 等），请原地更新现有条目——不要追加重复条目，导致旧值覆盖新值。
   • 运行格式化程序、类型检查、lint 和测试，然后验证真实追踪数据确实已写入 Latitude（步骤 6）。只有完成验证后，此项更改才算完成。

6. 验证监测是否有效 代码编译通过并不意味着监测已完成——只有在 Latitude 项目中确认了真实跨度，才算完成。尽可能自动完成这一闭环，而不是让用户检查 UI。如果具备凭据和安全路径：

   • 生成真实跟踪数据。 运行用户的实际 LLM 流程——每个用例组运行一次有代表性的流程——以生成真实跨度，而非合成测试跨度。等待流程完成或正常关闭，以便刷新缓冲的跨度；对于短生命周期脚本/作业，请在退出前执行 await latitude.flush()/latitude.shutdown()（Python：latitude.flush()）。强制终止可能会导致跨度丢失。
   • 使用最佳可用工具读取跟踪数据，按以下顺序：
     1. Latitude MCP，如果已连接并通过身份验证——使用其跟踪/搜索工具获取项目的近期跟踪数据。
     2. Latitude CLI，如果已安装并通过身份验证——latitude traces list --project-slug <slug> --format json（参见 latitude-cli）。
     3. 直接调用 Latitude API，作为后备方案——在 https://api.latitude.so 下的跟踪端点执行 GET 请求，并携带 Authorization: Bearer <LATITUDE_API_KEY>。可通过查阅文档或检查 CLI 底层请求来确认确切路径/参数（latitude traces list --schema，或 --debug / --format http）。
   • 跨度会按批次间隔导出，因此可能需要一点时间才能到达——请轮询，不要期待它们立即出现。
   • **确认质量，而不只是确认是否存在：**每个用例组都应有预期的跨度，模型和令牌计数正确，消息已捕获，跨度边界合理，并包含已设置的 userId/sessionId/标签/元数据。如果跨度缺失或有误，请修复并重新运行——循环操作，直到跟踪数据正确为止。 跟踪数据缺失/错误的常见原因：环境变量值或项目路由错误、在首次 LLM 调用后才初始化、未注册监测、智能过滤、在 capture() 之外消耗流，或进程在刷新前退出。
   • 不要对真实项目进行破坏性的“清理”。 这些验证运行会在用户的项目中留下真实跟踪数据——这是预期行为。删除并重新创建项目以清理迭代过程中产生的杂乱跟踪数据，仅适用于 latitude-setup 中的零账户流程（临时项目）；绝不要删除并重新创建用户已有的项目。尽量减少验证运行次数。

还没有账户？零账户 CLI 引导流程

如果任何地方都没有可用的 LATITUDE_API_KEY，只问一个问题，并根据回答采取行动；绝不要在回合结束时要求用户提供密钥：

Do you already have a Latitude account?
  (a) No, create a temporary one for me now, no signup, I'll claim it later   (default)
  (b) Yes, I'll give you its API key and project slug

如果用户选择（a）、没有回答，或表示“直接帮我处理”，请在开始监测前移交给 latitude-setup 技能。它会使用 latitude CLI 引导创建临时账户，无需注册——返回 API 密钥、一个项目 slug 和用于认领所有权的浏览器链接——将 LATITUDE_API_KEY 和 LATITUDE_PROJECT_SLUG 写入 .env（或运行环境的配置）中，然后返回此处，使用该 projectSlug 开始监测，并以创建第一个 Artifact 结束。如果用户选择（b），则等待其提供相应值，然后继续直接路径。

引导流程中的 projectSlug 在 latitude-setup 删除并重新创建项目以清理跟踪数据的步骤中保持稳定（项目名称相同 → slug 相同），因此只需写入一次 LATITUDE_PROJECT_SLUG；清理时不需要重新编辑。

除了“应用中已有”和“通过 Latitude MCP 发现”（见下文）之外，这是获取配置值的第三种方式。优先采用当前适用的方式，顺序为：已有值 → 通过 Latitude MCP 发现（用户已有账户）→ 通过 latitude-setup 进行 CLI 引导（尚无账户）。

Latitude MCP 辅助配置

在添加 Latitude 遥测且配置值缺失或不明确时，请使用本节。Latitude MCP 是一个位于 https://api.latitude.so/v1/mcp 的远程 OAuth 身份验证 MCP 服务，可向 Agent 提供 Latitude 工作区数据和操作。遥测不要求连接它，但连接后应使用它来减少与用户的来回沟通。

• 先检查 MCP 是否可用。 在询问用户 Latitude 项目/API 密钥详情之前，检查当前 Agent 框架中可用的已连接 MCP 工具/服务。如果有可用且已通过身份验证的 Latitude MCP 服务，请使用它发现组织/项目信息，并协助准备遥测配置。
• 在制定计划之前，先询问是否安装 MCP，以澄清需求。 如果尚未连接 Latitude MCP，请先暂停，不要展示实施计划；询问用户是否想安装/连接它，以便 Agent 自动发现项目并协助填写可配置的遥测变量。简要说明 Latitude MCP 可通过 OAuth 授权范围，让 Agent 访问其 Latitude 工作区，包括项目、密钥、跟踪记录、注释、评分、搜索、问题、数据集和其他 Latitude 资源；用户可在 设置 → 密钥 → OAuth 密钥 中撤销已连接的 Agent。未经明确批准，不要安装或配置 MCP。不要将 MCP 相关问题与实施计划或批准请求合并。如果用户拒绝，请继续正常的手动配置流程，然后再展示实施计划。
• 使用 MCP 填写非机密配置。 如果用户已指出应接收跟踪记录的 Latitude 项目，或代码库已明确暗示该项目，请优先使用 MCP 提供的项目信息来确定正确的 LATITUDE_PROJECT_SLUG。如果存在多个可能的项目，请列出选项并请用户选择。
• 仅在安全的情况下，使用 MCP 创建密钥/获取元数据。 如果 Latitude MCP 提供 API 密钥管理功能，仅在用户批准后使用，并且只能用于创建或识别所需的密钥元数据。不要在聊天中显示真实的 API 密钥值。只有在框架/工具支持安全操作时，才将密钥直接存入项目现有的密钥管理器；否则，请在环境变量示例/文档中添加占位符，并告知用户真实值的存储位置。
• 不要询问 MCP 能够回答的问题。 如果 MCP 能够列出项目、推断 slug 或确认现有密钥名称，请先完成这些操作，再询问用户。只询问 MCP 无法确定的事项，例如在项目不明确时应由哪个项目接收跟踪记录、是否创建新的 API 密钥，或应将密钥存储在哪里。
• 将 MCP 与应用遥测分开。 MCP 用于帮助配置 Latitude；它不会跟踪目标应用的大模型调用。应用仍需配置遥测 SDK 或 OTLP 导出器，并设置 LATITUDE_API_KEY 和 LATITUDE_PROJECT_SLUG，或配置等效的 OTLP 标头。

配置值

要求用户提供配置时，请说明每个值的用途以及获取方式：

• LATITUDE_API_KEY：用于向 Latitude 上传数据的身份验证。已有账户的用户可在 Settings → API Keys 下查找或创建密钥；latitude-setup 会为新的临时账户创建密钥。只有在用户选择提供自己的密钥时才说明这一点；否则不要索要。
• LATITUDE_PROJECT_SLUG：用于选择接收跟踪数据的 Latitude 项目。在 Latitude 应用中打开项目；slug 会显示在侧边栏的标题区域。它是项目的短标识符，不是显示名称。
• 通用 OTLP 设置会将相同的值配置为 OTLP 跟踪数据端点 https://ingest.latitude.so/v1/traces，以及 请求头 Authorization=Bearer <api-key> 和 X-Latitude-Project=<project-slug>。请通过应用已有的机制设置这些值——变量名因应用或框架而异（OTel 的约定是 OTEL_EXPORTER_OTLP_[TRACES_]ENDPOINT / …_HEADERS，但应用可能使用不同的名称，或在代码中配置 exporter），因此请根据应用实际情况设置，不要假定名称固定。
• 任何包含空格的 .env 值都必须加引号。 Latitude CLI 使用严格的解析器从 .env 读取 LATITUDE_API_KEY，遇到第一个未加引号且包含空格的值时就会停止——因此，未加引号的请求头或令牌值（例如包含 Bearer 的值）会导致 CLI 无法读取密钥。请将此类值用双引号括起来；Node 的 --env-file 和其他加载器会移除引号，因此加引号的 .env 文件可通用。详情请参阅 latitude-cli → Authentication。

如果项目已有密钥管理器，切勿在聊天中索要真实密钥值。请询问用户希望将其存储在哪里，并且只在环境变量示例或文档中添加占位符。

适用哪种集成？

编写代码前，先根据应用的技术栈匹配表中的一行。对应行的 Latitude 文档页面是准确代码片段的权威来源（https://docs.latitude.so/telemetry/<path>.md 会返回易读版本）；机制列会指明应遵循本指南中的哪个部分。此表会不断扩充，因此只能将其视为当前快照；请检查 https://docs.latitude.so/llms.txt，查看表中未列出的页面。

目标	TypeScript	Python	文档页面
OpenAI、Azure OpenAI	createOpenAIInstrumentation(OpenAI)（Azure 复用此方法）	{"openai": openai}	providers/openai、providers/azure
OpenAI Agents SDK	createOpenAIAgentsInstrumentation(OpenAIAgentsSDK)	{"openai-agents": agents}（唯一带连字符的 Python 键）	frameworks/openai-agents
Anthropic	createAnthropicInstrumentation(AnthropicSDK)	{"anthropic": anthropic}	providers/anthropic
Amazon Bedrock	createBedrockInstrumentation(BedrockSDK)	{"bedrock": boto3}	providers/amazon-bedrock
Amazon SageMaker	OTLP 导出器	{"sagemaker": boto3}	providers/sagemaker
Cohere	createCohereInstrumentation(CohereSDK)	{"cohere": cohere}	providers/cohere
Together AI	createTogetherAIInstrumentation(TogetherSDK)	{"togetherai": together}	providers/together-ai
Vertex AI	createVertexAIInstrumentation(VertexAISDK)	{"vertexai": vertexai}	providers/vertex-ai
Google AI Platform	createAIPlatformInstrumentation(AIPlatformSDK)	{"aiplatform": aiplatform}	providers/google-ai-platform
Google Gemini（google-genai）	OTLP 导出器	{"google_generativeai": genai}	providers/gemini
Groq、Mistral、Ollama、Replicate、watsonx、Aleph Alpha、Transformers	OTLP 导出器	{"groq": groq}、{"mistralai": mistralai}、{"ollama": ollama}、{"replicate": replicate}、{"watsonx": ibm_watsonx_ai}、{"aleph_alpha": aleph_alpha_client}、{"transformers": transformers}	providers/<name>
LangChain	使用 @langchain/core/callbacks/manager 的 createLangChainInstrumentation(CallbackManagerModule)	{"langchain": langchain_core}	frameworks/langchain
LlamaIndex	createLlamaIndexInstrumentation(LlamaIndex)	{"llamaindex": llama_index}	frameworks/llamaindex
Google ADK、CrewAI、Haystack、LiteLLM	不可用	{"google_adk": google.adk}、{"crewai": crewai}、{"haystack": haystack}、{"litellm": litellm}	frameworks/<name>
DSPy	不可用	对 LiteLLM 进行插桩：{"litellm": litellm}（没有 dspy 键）	frameworks/dspy
Pydantic AI	不可用	使用不带插桩的 Latitude(...)，然后调用 Agent.instrument_all()	frameworks/pydantic-ai
Strands Agents	不可用	通过环境变量配置 OTLP：基础 URL 为 https://ingest.latitude.so（不带 /v1/traces）、请求头、OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf、OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental	frameworks/strands
Vercel AI SDK v6	使用不带插桩的 Latitude，并在每次调用时设置 experimental_telemetry: { isEnabled: true, tracer: latitude.getTracer("vercelai") }	不可用	frameworks/vercel-ai-sdk
Vercel AI SDK v7	使用不带插桩的 Latitude，并通过 @ai-sdk/otel 中的 registerTelemetry(new OpenTelemetry()) 注册（选择退出，无需逐次调用设置标记）；将系统提示词通过顶层的 instructions 传入，而不是作为 system 消息	不可用	frameworks/vercel-ai-sdk-v7
Cloudflare Think	使用 beforeTurn() 中的 experimental_telemetry 和 latitude.getTracer("cloudflare-think", context)；辅助函数位于 @latitude-data/telemetry/cloudflare；在 Workers 上绝不能调用 capture.start()，也绝不能在 beforeTurn() 内调用 new Latitude()	不可用	frameworks/cloudflare-think
Cloudflare AI Gateway	在网关控制面板中配置 OTLP（端点 + Authorization + x-latitude-project 请求头），无需 SDK	同上	frameworks/cloudflare-ai-gateway
Mastra	将 @mastra/otel-exporter 指向 https://ingest.latitude.so/v1/traces 并设置两个请求头，无需 Latitude SDK	不可用	frameworks/mastra
Eve	使用 @vercel/otel 的 registerOTel 和 OTLPTraceExporter，将其指向摄取 URL 并设置两个请求头，无需 Latitude SDK	不可用	frameworks/eve
Flue	使用不带插桩的 Latitude，并通过 @flue/opentelemetry 中的 observe(createOpenTelemetryObserver())；内容仅在调用 exportContent() 时导出	不可用	frameworks/flue
LiveKit Agents	将 LatitudeSpanProcessor 附加到 LiveKit 自己的追踪器提供程序（而非 Latitude 类）；设置 disableSmartFilter: true 以保留 STT/TTS/VAD 跨度	同样使用 LatitudeSpanProcessorOptions(disable_smart_filter=True)	frameworks/livekit
ElevenLabs Agents	使用 OpenAI 插桩为你自己的兼容 OpenAI 的 LLM 代理进行插桩；STT/TTS 不可观测	同上	frameworks/elevenlabs
其他任何支持 OTLP 的对象（Go、Java、Ruby、.NET、自行实现的跨度）	OTLP 导出器	OTLP 导出器	otel-exporter
“OTLP 导出器”是指应用自身的 OpenTelemetry 导出器，目标地址为 https://ingest.latitude.so/v1/traces，并使用 Authorization: Bearer <key> 和 X-Latitude-Project: <slug>（见“其他目标”）。如果某种语言对应的行标注为“不可用”，该语言使用 OTLP 导出器。

TypeScript

使用项目的包管理器安装最新版本的 @latitude-data/telemetry。先初始化现有的 Sentry/Datadog/New Relic/Honeycomb/自定义 OTel，再初始化 Latitude。

instrumentations 是一个由各集成专属工厂创建的实例组成的数组，每个工厂都从自己的子路径导入。 旧版对象映射形式（instrumentations: { openai: OpenAI }）已在 v4 中移除，使用它会导致 latitude.ready 因迁移错误而拒绝；请勿使用。如果在应用中发现这种写法，请将其迁移。

import OpenAI from "openai";
import { Latitude } from "@latitude-data/telemetry";
import { createOpenAIInstrumentation } from "@latitude-data/telemetry/instrumentations/openai";

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: [createOpenAIInstrumentation(OpenAI)],
});

await latitude.ready; // await before creating the LLM client when first-call coverage matters

请使用项目实际的环境变量校验；此代码片段仅展示 SDK 的结构。

可用工厂分别位于 @latitude-data/telemetry/instrumentations/ 下的独立子路径中：openai、openai-agents、anthropic、bedrock、cohere、langchain、llamaindex、togetherai、vertexai、aiplatform（工厂名称为 create<Name>Instrumentation；见上表）。传入应用所导入的同一个 SDK 模块对象：对于命名空间包，使用 import * as AnthropicSDK from "@anthropic-ai/sdk"；对于 LangChain，传入 @langchain/core/callbacks/manager 模块，而不是 langchain 包。没有 TypeScript 工厂的提供方（Gemini、Groq、Mistral、Ollama、Replicate、SageMaker、watsonx、Aleph Alpha、Transformers）在 TypeScript 中使用 OTLP 导出器。

特殊情况（各行详情见表格）：Vercel AI SDK、Cloudflare Think、Flue 和 LiveKit 初始化 Latitude 时不传入 instrumentations，而是通过框架自身的钩子接入遥测；Mastra、Eve 和 Cloudflare AI Gateway 则完全不需要 Latitude SDK。

**自定义现有 OTel 提供方：**在现有处理器旁添加 new LatitudeSpanProcessor(apiKey, project)，并针对该提供方注册工厂：

import { LatitudeSpanProcessor, registerLatitudeInstrumentations } from "@latitude-data/telemetry";
import { createOpenAIInstrumentation } from "@latitude-data/telemetry/instrumentations/openai";

await registerLatitudeInstrumentations({
  instrumentations: [createOpenAIInstrumentation(OpenAI)],
  tracerProvider: sdk.getTracerProvider(),
});

在用例边界使用 capture(name, async () => { ... }, { userId, sessionId, tags, metadata, project })。对于多项目路由，project 会覆盖构造函数中的默认值。capture() 会为已插桩的跨度添加上下文；它本身不会创建 LLM 跨度。在 Cloudflare Workers 上请勿使用 capture.start() / scope.end()。

对于短暂运行的脚本/作业，请在退出前调用 await latitude.flush() 或 await latitude.shutdown()。对于长期运行的服务端，请勿逐请求调用 shutdown()。

Python

需要 Python 3.11 或更高版本。使用项目的包管理器安装最新版本的 latitude-telemetry。

import os
import openai
from latitude_telemetry import Latitude

latitude = Latitude(
    api_key=os.environ["LATITUDE_API_KEY"],
    project=os.environ["LATITUDE_PROJECT_SLUG"],
    instrumentations={"openai": openai},
)

如果已注册 OpenTelemetry 提供方，Latitude(...) 会挂接到该提供方。对于自定义配置，请将 LatitudeSpanProcessor 添加到现有提供方，并调用 register_latitude_instrumentations(instrumentations={...}, tracer_provider=provider)。

Python 保留字典形式：键 → 导入的模块对象（绝不是字符串）。截至撰写本文时，可用键包括：openai、openai-agents（模块 agents）、anthropic、bedrock 和 sagemaker（均为 boto3）、cohere、togetherai（模块 together）、vertexai 和 aiplatform（均来自 google-cloud-aiplatform）、google_generativeai（来自 google-genai 的模块 genai）、google_adk（google.adk）、langchain（langchain_core）、llamaindex（llama_index）、crewai、haystack（来自 haystack-ai）、litellm（也是 DSPy 使用的键）、groq、mistralai、ollama、replicate、watsonx（ibm_watsonx_ai）、aleph_alpha（aleph_alpha_client）、transformers。有几个键与包名不同；请从表格或文档页面中复制准确的键值对。Pydantic AI 和 Strands 不使用键（见表格）。

使用 capture() 作为包装器，并采用 snake_case 选项，尤其是在上下文按请求区分时：

from latitude_telemetry import capture

def run_agent(user_id: str, session_id: str):
    return capture(
        "support-agent-run",
        lambda: agent.run(),
        {"user_id": user_id, "session_id": session_id, "tags": ["support"]},
    )

对于短暂运行的进程，请在退出前调用 latitude.flush() 或 latitude.shutdown()。对于长期运行的服务，请勿逐请求调用 shutdown()。

Other targets

• 通用 OTLP / 其他语言：向 https://ingest.latitude.so/v1/traces 发送追踪数据，并附上 Authorization: Bearer <LATITUDE_API_KEY> 和 X-Latitude-Project: <LATITUDE_PROJECT_SLUG>（application/json 或 application/x-protobuf；返回 202 表示已接受）。使用与 SDK 无关的环境变量时，对应设置为 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 加上 OTEL_EXPORTER_OTLP_TRACES_HEADERS；有些框架（Pydantic AI、Strands）会在 OTEL_EXPORTER_OTLP_ENDPOINT 中接收基础 URL https://ingest.latitude.so，并自行追加路径。若要获取完整的模型、令牌和消息详情，LLM span 必须遵循 OpenTelemetry GenAI 语义约定（gen_ai.* 属性）；otel-exporter 文档页提供 curl、Go、Java、Ruby 和 .NET 示例，以及可选的 latitude.*、session.id、user.id 属性。
• 编码 Agent / harness 遥测：此类遥测追踪的是 Agent harness 自身的提示词、响应和工具 I/O，而不是应用的 LLM 调用。请将两者分开，并且在安装任何 hook 或插件前先征求用户同意，因为内容会发送到 Latitude；如果存在仅结构模式，请提供该模式。每种 harness 都会从自己的位置读取密钥和项目，因此请遵循其文档页（telemetry/<name>），而不要采用 .env 约定。新的 harness 会陆续添加；截至撰写本文时：
  • Claude Code：npx -y @latitude-data/claude-code-telemetry@latest install（非交互模式：--api-key=… --project=<slug> --yes）。此命令会将 env 块和 Stop/SessionEnd hooks 写入 ~/.claude/settings.json；仅读取 LATITUDE_PROJECT。仅支持完整内容；使用 LATITUDE_REDACT_ATTRIBUTES 进行脱敏。
  • **Hermes：**将 latitude-telemetry-hermes 安装到运行 Hermes 的 Python 环境中（官方安装命令：~/.hermes/bin/uv pip install --python ~/.hermes/hermes-agent/venv/bin/python latitude-telemetry-hermes）。在 ~/.hermes/config.yaml 的 plugins.enabled 中添加 latitude 以启用（不要使用 hermes plugins enable），并设置 plugins.stream_reasoning_deltas: true 以获取首个令牌耗时。将凭据作为 LATITUDE_API_KEY 和 LATITUDE_PROJECT（或 LATITUDE_PROJECT_SLUG）写入 ~/.hermes/.env。仅结构模式：LATITUDE_NO_CONTENT=true。之后重启 Hermes（及其网关）。
  • OpenClaw：npx -y @latitude-data/openclaw-telemetry-cli@latest install（非交互模式：--api-key=… --project=<slug> --yes --restart；仅结构模式：--no-content）。需要 OpenClaw 2026.8.1 或更高版本。此命令会通过 --accept-capabilities 安装 @latitude-data/openclaw-telemetry 插件，将 plugins.entries["@latitude-data/openclaw-telemetry"] 写入 ~/.openclaw/openclaw.json，并同时设置 config.allowConversationAccess 和 hooks.allowConversationAccess（后者是 OpenClaw 自身的门控；若未设置，则完全不会导出追踪数据），验证配置并重启网关。将 config.debug 设为 true 后，运行 grep latitude-openclaw /tmp/openclaw/openclaw-*.log 进行验证。OpenClaw 捆绑的 @openclaw/diagnostics-otel 导出器也能连接到 Latitude，但会清除会话、运行和用户 ID，且不会导出系统提示词、工具定义或记忆，因此 Sessions、Users、Tools 和 Memory 会保持为空；不要同时运行两者，否则同一次模型调用会被计数两次。
  • Pi：npx -y @latitude-data/pi-telemetry install（非交互模式：--api-key=… --project=<slug> --yes；仅结构模式：--no-content）。此命令会写入 ~/.pi/agent/settings.json 和 ~/.pi/agent/latitude-telemetry.json；读取 LATITUDE_PROJECT 或 LATITUDE_PROJECT_SLUG。
  • **Prime Intellect (Verifiers)：**将 latitude-telemetry-prime-intellect 通过 pip install latitude-telemetry-prime-intellect 安装到评估环境中，在环境变量中设置 LATITUDE_API_KEY 和 LATITUDE_PROJECT（或 LATITUDE_PROJECT_SLUG）；通过 make_on_complete(...) / export_episodes(...) 导出，或事后使用 latitude-prime-intellect-export export <run-dir> 导出。奖励会作为自定义评分记录。仅结构模式：LATITUDE_NO_CONTENT=true。
• 来自其他平台的历史追踪数据：Langfuse、LangSmith 和 Braintrust 的历史数据不会通过插桩采集，而是会被导入：在 UI 中前往 Project settings → Imports，或通过 MCP、CLI 或 API 调用 createImport 操作（使用 getImport / retryImport / cancelImport 跟踪导入进度）。导入仅支持云端，每个组织一次只能进行一个，按从新到旧的顺序处理，且受套餐用量限制；导入完成后会丢弃凭据。文档：telemetry/imports/overview。如果审计发现用户已有 Langfuse/LangSmith/Braintrust 设置，并希望保留其历史记录、同时将实时流量切换到 Latitude，请提供此选项。

长期记忆？添加记忆可观测性

如果应用具有长期记忆——即 Agent 在不同交互之间持久化并重新加载的状态——强烈建议同时为其记忆操作埋点。这样即可启用 Latitude 的 Memory 页面：查看每个存储的内容、每条记录的变更历史和差异、每个会话读写的 token 数，以及每次写入对应的会话。记忆操作使用同一条遥测管道，因此无需额外设置账户或导出器——只需添加记忆专用的 span。

• 什么算长期记忆。 指 Agent 写下来以供后续使用，并在之后的交互中读回的状态——文件（memory/ 目录、每位用户的笔记）、由 Agent 填充并查询的记忆型数据库表、Agent 既写入又会通过语义搜索来回忆内容的向量存储、用于保存每位用户持久状态的键值/Redis 存储，或 Mem0/Zep/Supermemory 等服务提供商。它会跨会话、运行或用户持久保留。
• 什么不算长期记忆（不要作为记忆埋点）：单个请求或会话中的对话/消息历史（那本身就是 trace）、提示词上下文和少样本示例、纯性能缓存，以及 Agent 只查询、不写入的只读参考语料库（这属于检索，而非记忆）。
• **如何判断：**你已在审计期间检查过代码库——查找 Agent 主动跨越的持久化边界（例如 remember/recall/store/retrieve/upsert 等函数、memory/ 模块、Agent 既会写入又会查询的向量存储客户端，或记忆服务提供商的 SDK 导入）。
• 如果应用有长期记忆，请在确认基础追踪正常后阅读**memory.md**（随此技能附带），并遵照其中说明——它涵盖存储/记录模型、在何处以及何时发出数据、记忆 SDK 辅助工具，以及原始 gen_ai.memory.* span。如果没有，则无需额外操作；没有记忆需要观测。