traceway-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set Up Traceway

配置 Traceway

Analyze the application first, agree on its Traceway project structure with the user, help them create that structure in the dashboard, and only then integrate and verify it.

先分析应用，与用户就 Traceway 项目结构达成一致，帮助他们在 dashboard 中创建该结构，然后才能进行集成与验证。

Operating Contract

操作约定

Inspect before asking for credentials or changing code.
Explain what was detected, what is already tracked, and how each production component should report to Traceway.
Present a proposed project map and wait for the user to confirm it before implementation.
There are two classes of credentials, treated differently:
- Setup tokens (prefix
```
tws_
```
  ) are org-scoped, expire in 6 hours, and can only propose a setup plan; nothing is created until the user approves the plan on the Traceway website. They are designed to transit chat, and asking the user to paste one is expected.
- Project ingest tokens and upload tokens are long-lived. Never print their values, never ask the user to paste them into chat, and never commit them. When Step 3's apply script (or the
```
traceway
```
  CLI) writes an approved plan's ingest tokens into env files, read only the variable names and statuses from its output, never the values.
Never print token values found in files or the environment. Report only that a value exists and the variable name that carries it.
Never commit tokens or filled connection strings.

在询问凭据或修改代码之前先进行检查。
解释检测到了什么、已经跟踪了什么，以及每个生产组件应如何向 Traceway 上报。
提出项目映射，并在实施前等待用户确认。
凭据分为两类，处理方式不同：
- Setup token（前缀为
```
tws_
```
  ）的作用域是 organization，有效期为 6 小时，只能用于提出设置计划；在用户于 Traceway 网站上批准计划之前，不会创建任何内容。这类 token 专供通过聊天传输，因此询问用户粘贴一个是预期行为。
- 项目 ingest token 和 upload token 是长期有效的。绝不打印其值，绝不要求用户将其粘贴到聊天中，也绝不提交到版本库。当步骤 3 的 apply 脚本（或
```
traceway
```
  CLI）把已批准计划中的 ingest token 写入 env 文件时，只读取其输出中的变量名和状态，绝不读取值。
绝不打印在文件或环境变量中找到的 token 值。只报告该值是否存在，以及承载它的变量名。
绝不提交 token 或已填入凭据的连接字符串。

Invocation Forms

调用形式

Invocation carries	Path
A project ingest token + url	Fast Path for a single component, otherwise Steps 1-2, then integrate against the existing project
A setup token ( `tws_` ) + url	Steps 1-2, then Step 3 from "Write the plan file" (3b)
No token	Steps 1-2, then Step 3 from the top

Every backend integrates with OpenTelemetry. There is one backend path, not one per language or web framework: Go, Node, Python, PHP, Java, .NET, Ruby, and everything else export OTLP/HTTP to

<instance>/api/otel/*

. The Traceway project is created with framework OpenTelemetry, which is the only backend option in the dashboard's framework picker. The native Traceway Go SDK is a deliberate exception used only when the user explicitly asks for it.

调用携带的信息	路径
项目 ingest token + url	单一组件使用快速路径；否则执行步骤 1-2，然后针对现有项目进行集成
setup token（ `tws_` ）+ url	执行步骤 1-2，然后从步骤 3 的“编写计划文件”（3b）开始
没有 token	执行步骤 1-2，然后从步骤 3 开始

所有后端都集成 OpenTelemetry。 后端只有一条集成路径，而不是按语言或 Web 框架划分：Go、Node、Python、PHP、Java、.NET、Ruby 及其他所有语言均通过 OTLP/HTTP 导出到

<instance>/api/otel/*

。Traceway 项目使用 OpenTelemetry 框架创建，它是 dashboard 框架选择器中唯一的后端选项。只有在用户明确要求时，才例外使用原生 Traceway Go SDK。

Fast Path

快速路径

When all of the following hold, skip Steps 2 and 3 and go straight to the integration steps:

the repository has exactly one deployable component, and
the user supplied (or the environment already carries) an instance URL and a project ingest token (not a
```
tws_
```
setup token, which exists to create projects), and
the token's project already matches that component.

Still run Step 1, because it decides how to instrument. Collapse "Propose and Confirm the Project Map" to a single confirmation line ("This is a Go API; it reports to your existing

<name>

project over OpenTelemetry") and skip the project-creation step entirely. The full map-and-creation ceremony exists for repositories with more than one deployable component, or where no project exists yet. Do not make a user who handed you a token sit through a project-map review for a single service.

同时满足以下所有条件时，跳过步骤 2 和 3，直接进入集成步骤：

仓库恰好包含一个可部署组件；并且
用户已提供（或环境中已存在）instance URL 和项目 ingest token（而不是用于创建项目的
```
tws_
```
setup token）；并且
该 token 所属项目已经与该组件匹配。

仍需执行步骤 1，因为该步骤决定如何添加检测。将“提出并确认项目映射”压缩为一行确认信息（“这是一个 Go API；它通过 OpenTelemetry 向现有的

<name>

项目上报”），并完全跳过项目创建步骤。对于单一服务，不要让已经提供 token 的用户再经历项目映射评审。

完整的映射与创建流程仅用于包含多个可部署组件的仓库，或者尚未创建任何项目的场景。

Step 1: Analyze the Architecture

步骤 1：分析架构

Before changing anything, build a picture of what is deployed and what is already instrumented:

Frameworks and languages: detect them from
```
package.json
```
,
```
go.mod
```
,
```
composer.json
```
,
```
requirements.txt
```
/
```
pyproject.toml
```
,
```
pubspec.yaml
```
,
```
build.gradle
```
(
```
.kts
```
),
```
Package.swift
```
,
```
*.xcodeproj
```
/
```
*.xcworkspace
```
,
```
Podfile
```
, and source extensions. For iOS/Apple targets, note whether the sources are Swift or Objective-C. That choice picks the path in "Frontend and Mobile" (Swift gets the native SDK; Objective-C-only has none and falls back to OTel).
Deployable components and entry points: inventory APIs, SSR servers, browser apps, workers, schedulers, CLIs, and mobile applications. Treat code organization as evidence, not proof that something is deployed. Note the deployment target while you are here: Kubernetes manifests, a Helm chart, Kustomize overlays,
```
Dockerfile
```
plus a compose file, or cloud-init / Ansible / Terraform. It decides the host-metrics path in Step 8.
Existing observability: find OpenTelemetry configuration, Traceway SDKs, Sentry, Datadog, New Relic, Honeycomb, logging exporters, tracing middleware, source map or symbol upload steps, and observability environment-variable names. Explain whether Traceway will replace, coexist with, or extend each integration. Never display discovered credential values.
Production role of JS meta-frameworks (Next.js, SvelteKit, Remix, Nuxt): never assume full-stack.
- Frontend-only signals:
```
output: 'export'
```
  in
```
next.config.*
```
  (static export, so there is no server in production); no API routes (
```
app/api/**/route.*
```
  ,
```
pages/api/*
```
  ) or only trivial ones; no
```
'use server'
```
  server actions;
```
rewrites
```
  /proxy config or a
```
NEXT_PUBLIC_API_URL
```
  -style env var pointing the browser at an external API; a separate backend service in this repo, another repo, or another language; static hosting in the deploy config (S3/CloudFront, GitHub Pages, nginx serving
```
out/
```
  ).
- Server signals: API routes with real logic,
```
'use server'
```
  server actions, database clients imported in server code, SSR reading its own data layer,
```
next start
```
  or standalone output in the deploy config.
- Mixed or unclear: ask how the application is deployed and whether the framework server does production work worth tracking.
Frontend-only means integrate ONLY the browser side with the frontend SDK; do NOT add OTel to, or otherwise instrument, the framework's server side. A separate backend is its own component with its own Traceway project.
Background work: find cron jobs, queue consumers, schedulers, CLI commands, and long-running workers. Record whether libraries already emit
```
CONSUMER
```
spans.
AI/LLM usage: check dependencies for
```
openai
```
,
```
@anthropic-ai/sdk
```
,
```
anthropic
```
,
```
langchain
```
/
```
@langchain/*
```
,
```
ai
```
(Vercel AI SDK),
```
litellm
```
,
```
google-generativeai
```
,
```
cohere
```
,
```
openrouter
```
, and agent frameworks (
```
langgraph
```
,
```
crewai
```
,
```
autogen
```
/
```
ag2
```
,
```
pydantic-ai
```
,
```
@openai/agents
```
,
```
@mastra/*
```
,
```
llamaindex
```
/
```
llama-index
```
,
```
semantic-kernel
```
). Then decide whether this is a conversational product (chatbot, assistant, agent) rather than one-shot LLM calls: look for chat or streaming-chat routes (
```
/chat
```
,
```
/completions
```
, SSE or websocket handlers feeding an LLM), message-history persistence (a
```
messages
```
/
```
conversations
```
table or thread ids), tool/function-calling definitions passed to the model, or any agent framework above. If conversational or tool-calling, read
```
ai-agent.md
```
in this skill directory before proposing the AI integration.
Browser build and release flow: identify the bundler, output directory, source-map settings, deploy pipeline, and existing artifact uploads.
Mobile build and release flow: determine whether Flutter is obfuscated, Android uses R8/minification, iOS produces dSYMs, and whether multiple platform directories are one cross-platform product or independently released apps.
Deployment and host metrics: inspect Dockerfiles, Compose, Kubernetes, Helm, Terraform, Ansible, cloud-init, PaaS configs, and CI/CD. Determine whether the backend runs on a host where the Traceway OTel Agent is applicable.

Present the findings before asking questions:

Component	Repository evidence	Production role	Current tracking	Proposed Traceway project	Integration	Credentials needed
`apps/api`	Go module + Gin routes	Backend API	OTel / none / vendor	`Product Backend`	OTel	Runtime token
`apps/web`	Svelte + Vite	Browser app	Existing SDK / none	`Product Web`	Traceway Svelte SDK	Runtime + upload token

Use actual paths and findings. Include unresolved deployment assumptions explicitly.

在修改任何内容之前，先弄清部署了哪些内容，以及已经对哪些内容进行了检测：

框架和语言：从
```
package.json
```
、
```
go.mod
```
、
```
composer.json
```
、
```
requirements.txt
```
/
```
pyproject.toml
```
、
```
pubspec.yaml
```
、
```
build.gradle
```
（
```
.kts
```
）、
```
Package.swift
```
、
```
*.xcodeproj
```
/
```
*.xcworkspace
```
、
```
Podfile
```
和源代码扩展名中进行检测。对于 iOS/Apple target，记录源代码使用 Swift 还是 Objective-C。该选择决定“前端与移动端”中的路径（Swift 使用原生 SDK；仅支持 Objective-C 时没有对应 SDK，因此回退到 OTel）。
可部署组件和入口点：盘点 API、SSR server、browser app、worker、scheduler、CLI 和移动应用。代码组织结构只能作为证据，不能证明某项内容确实已部署。同时记录部署 target：Kubernetes manifest、Helm chart、Kustomize overlay、
```
Dockerfile
```
加 compose 文件，或 cloud-init / Ansible / Terraform。它决定步骤 8 中的主机指标路径。
现有可观测性：查找 OpenTelemetry 配置、Traceway SDK、Sentry、Datadog、New Relic、Honeycomb、日志 exporter、tracing middleware、source map 或 symbol 上传步骤，以及可观测性环境变量名。说明 Traceway 将替换、与之共存还是扩展每项集成。绝不显示发现的凭据值。
JS meta-framework 的生产角色（Next.js、SvelteKit、Remix、Nuxt）：绝不能默认认为它是全栈应用。
- 仅前端信号：
```
next.config.*
```
  中存在
```
output: 'export'
```
  （静态导出，因此生产环境没有 server）；没有 API routes（
```
app/api/**/route.*
```
  、
```
pages/api/*
```
  ）或只有简单 API routes；没有
```
'use server'
```
  server actions；存在
```
rewrites
```
  /proxy 配置，或
```
NEXT_PUBLIC_API_URL
```
  一类 env var 指向浏览器访问的外部 API；仓库中存在独立后端服务，或后端位于其他仓库或使用其他语言；部署配置为静态托管（S3/CloudFront、GitHub Pages、nginx 提供
```
out/
```
  ）。
- 服务端信号：API routes 包含真实逻辑、存在
```
'use server'
```
  server actions、在 server 代码中导入数据库客户端、SSR 读取自身数据层，或部署配置中使用
```
next start
```
  或 standalone output。
- 混合或不明确：询问应用的部署方式，以及 framework server 是否在生产环境中执行值得跟踪的工作。
仅前端意味着只使用 frontend SDK 集成 browser 端；不要向 framework server 端添加 OTel 或以其他方式进行检测。独立后端是一个单独组件，需要拥有自己的 Traceway 项目。
后台工作：查找 cron job、queue consumer、scheduler、CLI command 和长时间运行的 worker。记录相关 library 是否已经发出
```
CONSUMER
```
span。
AI/LLM 使用：检查依赖中是否存在
```
openai
```
、
```
@anthropic-ai/sdk
```
、
```
anthropic
```
、
```
langchain
```
/
```
@langchain/*
```
、
```
ai
```
（Vercel AI SDK）、
```
litellm
```
、
```
google-generativeai
```
、
```
cohere
```
、
```
openrouter
```
，以及 Agent framework（
```
langgraph
```
、
```
crewai
```
、
```
autogen
```
/
```
ag2
```
、
```
pydantic-ai
```
、
```
@openai/agents
```
、
```
@mastra/*
```
、
```
llamaindex
```
/
```
llama-index
```
、
```
semantic-kernel
```
）。然后判断它是否是对话式产品（chatbot、assistant、Agent），而不是一次性 LLM 调用：查找 chat 或 streaming-chat route（
```
/chat
```
、
```
/completions
```
、为 LLM 提供数据的 SSE 或 websocket handler）、消息历史持久化（
```
messages
```
/
```
conversations
```
table 或 thread id）、传递给模型的 tool/function-calling 定义，或上述任一 Agent framework。如果属于对话式或涉及 tool-calling，在提出 AI 集成方案前，阅读此 skill 目录中的
```
ai-agent.md
```
。
Browser 构建和发布流程：确定 bundler、输出目录、source map 设置、部署 pipeline，以及已有的 artifact 上传流程。
Mobile 构建和发布流程：确定 Flutter 是否启用混淆、Android 是否使用 R8/minification、iOS 是否生成 dSYM，以及多个平台目录是一个跨平台产品还是独立发布的应用。
部署和主机指标：检查 Dockerfile、Compose、Kubernetes、Helm、Terraform、Ansible、cloud-init、PaaS 配置和 CI/CD。确定后端是否运行在适用 Traceway OTel Agent 的 host 上。

提出问题之前先展示检测结果：

组件	仓库证据	生产角色	当前跟踪状态	建议的 Traceway 项目	集成方式	所需凭据
`apps/api`	Go module + Gin routes	Backend API	OTel / none / vendor	`Product Backend`	OTel	运行时 token
`apps/web`	Svelte + Vite	Browser app	Existing SDK / none	`Product Web`	Traceway Svelte SDK	运行时 + upload token

使用真实路径和实际检测结果。明确列出尚未解决的部署假设。

Step 2: Propose and Confirm the Project Map

步骤 2：提出并确认项目映射

Explain these default boundaries:

Application boundary	Traceway project	What belongs in it
Backend system	One project with framework OpenTelemetry	API endpoints, child spans, issues, background tasks, AI traces, logs, application/runtime metrics, and host metrics. APIs, workers, schedulers, and the host agent share the project token; distinguish them with stable `service.name` values.
Browser frontend	One separate project per deployed browser application, using React, Svelte, Vue.js, or jQuery	Browser errors, web vitals, session replay, distributed-trace linkage, source maps, and browser release metadata.
Mobile app	One separate project per independently released application, using Flutter, React Native, Android, or iOS	Mobile errors/crashes, replay where supported, and build symbols or mappings. A single Flutter product targeting Android and iOS normally uses one project; separate native apps use separate projects.
Full-stack JS app	Two projects when its server runs in production	Server-side work goes to the OpenTelemetry backend project; browser-side work goes to the browser project.

The dashboard's framework picker offers exactly these nine options: OpenTelemetry for every backend, React / Svelte / Vue.js / jQuery for browsers, and Flutter / React Native / Android / iOS for mobile. There is no Gin, Django, Laravel, Next.js, or Remix entry, and none is needed. A Next.js or Remix browser project selects React, and its server side selects OpenTelemetry like any other backend. The framework-specific setup for a backend lives on the project's Connection page, which asks for the language and web framework after the project exists.

Do not create one project per backend process by default. Keeping the API, workers, AI calls, and server metrics together preserves their operational context and distributed traces. Split backend projects only for a real product, ownership, access-control, compliance, or data-isolation boundary.

Ask the user to confirm only what the repository cannot establish safely:

Which detected components are deployed and should be tracked?
Traceway Cloud or self-hosted, and which organization should own the projects?
Are the proposed names and project boundaries correct?
Does the backend run on a VM/host, Kubernetes, or serverless/PaaS, and should host metrics be collected?
Do mobile directories represent one cross-platform product or separate released apps?

Each confirmed row must also settle what Step 3's plan file needs:

The framework value, one of the nine:

opentelemetry

react

svelte

vuejs

jquery

flutter

react-native

android

ios

The env wiring: which untracked env file holds the credential (
```
envFile
```
) and under which name (
```
envVar
```
), following the credential-naming rules above (public prefixes like
```
VITE_
```
/
```
PUBLIC_
```
/
```
NEXT_PUBLIC_
```
for browser values).
```
envFormat
```
is
```
token
```
when the code composes the connection string itself or the value feeds an OTLP Authorization header, and
```
connectionString
```
when the SDK init reads the full
```
<token>@<instance>/api/report
```
string straight from the variable.
The deployment placement, from Step 1's deployment analysis: when the credential cannot be hardcoded into the repository because of how the component is deployed (Vercel/Fly/K8s/CI-injected env, secret managers), add a
```
deployment
```
block with the platform name and the exact command or UI path, using the literal placeholder
```
<token>
```
for the value. The website substitutes the real value after approval; never put real tokens in the plan. A mobile project whose credential lives in build config usually gets a
```
deployment
```
block and no
```
envFile
```
.

Do not modify code until the user confirms this map.

说明以下默认边界：

应用边界	Traceway 项目	应包含的内容
Backend system	一个使用 OpenTelemetry 框架的项目	API endpoints、child span、issues、background task、AI trace、logs、application/runtime metrics 和 host metrics。API、worker、scheduler 和 host agent 共享项目 token；使用稳定的 `service.name` 值区分它们。
Browser frontend	每个已部署 browser application 使用一个独立项目，框架为 React、Svelte、Vue.js 或 jQuery	Browser errors、web vitals、session replay、distributed-trace linkage、source map 和 browser release metadata。
Mobile app	每个独立发布的应用使用一个独立项目，框架为 Flutter、React Native、Android 或 iOS	Mobile errors/crashes、受支持的 replay，以及 build symbol 或 mapping。单个同时面向 Android 和 iOS 的 Flutter 产品通常使用一个项目；独立原生应用使用独立项目。
Full-stack JS app	当 server 在生产环境运行时使用两个项目	Server 端工作进入 OpenTelemetry backend 项目；browser 端工作进入 browser 项目。

Dashboard 的框架选择器恰好提供以下九种选项：所有后端使用 OpenTelemetry，browser 使用 React / Svelte / Vue.js / jQuery，mobile 使用 Flutter / React Native / Android / iOS。没有 Gin、Django、Laravel、Next.js 或 Remix 选项，也不需要这些选项。Next.js 或 Remix 的 browser 项目选择 React，其 server 端与其他后端一样选择 OpenTelemetry。后端的 framework-specific 配置位于项目创建后的 Connection 页面，该页面会询问语言和 Web framework。

不要默认每个后端 process 创建一个项目。将 API、worker、AI call 和 server metric 放在同一个项目中，可以保留它们的运维上下文和 distributed trace。只有在存在真实的产品、所有权、访问控制、合规或数据隔离边界时，才拆分 backend 项目。

只询问仓库无法安全确定的以下事项：

检测到的哪些组件已经部署，并需要跟踪？
使用 Traceway Cloud 还是 self-hosted，以及项目应由哪个 organization 拥有？
建议的名称和项目边界是否正确？
Backend 运行在 VM/host、Kubernetes 还是 serverless/PaaS 上，是否需要收集 host metrics？
Mobile 目录表示一个跨平台产品，还是多个独立发布的应用？

每个确认后的条目还必须确定步骤 3 的计划文件所需内容：

Framework value，必须是以下九种值之一：
```
opentelemetry
```
、
```
react
```
、
```
svelte
```
、
```
vuejs
```
、
```
jquery
```
、
```
flutter
```
、
```
react-native
```
、
```
android
```
、
```
ios
```
。
Env wiring：哪个未纳入版本控制的 env 文件保存凭据（
```
envFile
```
），以及使用什么变量名（
```
envVar
```
），并遵循上述凭据命名规则。Browser 值需要使用
```
VITE_
```
/
```
PUBLIC_
```
/
```
NEXT_PUBLIC_
```
等 public 前缀。当代码自行组装连接字符串，或该值用于 OTLP Authorization header 时，
```
envFormat
```
为
```
token
```
；当 SDK 初始化时直接从变量读取完整的
```
<token>@<instance>/api/report
```
字符串时，
```
envFormat
```
为
```
connectionString
```
。
Deployment placement，来自步骤 1 的部署分析：当组件的部署方式导致凭据无法硬编码到仓库中时，例如 Vercel/Fly/K8s/CI 注入 env 或 secret manager，应添加
```
deployment
```
block，其中包含 platform 名称和准确命令或 UI 路径，并使用字面占位符
```
<token>
```
表示值。Website 会在批准后替换真实值；绝不把真实 token 放入计划。凭据保存在构建配置中的 mobile 项目通常需要
```
deployment
```
block，而不需要
```
envFile
```
。

在用户确认该映射之前，不要修改代码。

Step 3: Create the Projects

步骤 3：创建项目

The default path: submit the confirmed map as a setup plan, the user approves it visually on the Traceway website, and a short curl script writes the resulting ingest tokens into env files. Nothing needs to be installed beyond

curl

and

jq

. Existing correctly mapped Traceway projects may be reused (the plan matches projects by name, so listing an existing name reuses it instead of duplicating).

默认路径：将确认后的映射作为 setup plan 提交，用户在 Traceway website 上以可视化方式批准，然后通过一个简短的 curl script 将生成的 ingest token 写入 env 文件。除

curl

和

jq

外无需安装任何东西。已存在且映射正确的 Traceway 项目可以复用；计划按名称匹配项目，因此列出已有名称会复用该项目，而不是创建重复项目。

3a. Get a setup token (skip when the invocation carried one)

3a. 获取 setup token（调用中已携带时跳过）

Branch on account state; ask only if the repository and conversation do not establish it:

Has a Traceway account: "Open
```
<instance>/setup
```
(Traceway Cloud: https://cloud.tracewayapp.com/setup). Log in if prompted; the page shows a setup token starting with
```
tws_
```
. Paste it here and keep the page open." The token expires in 6 hours; the page has a Generate New Token button.
No account yet: "Open
```
<instance>/register
```
(Traceway Cloud: https://cloud.tracewayapp.com/register). Step 1 creates your account and organization. On step 2, keep 'AI' selected; it shows a setup token starting with
```
tws_
```
. Paste it here and leave that page open: my proposal will appear there for your approval, and the projects show up live once you approve."

Do not have the user create projects in the web UI on this path, and do not proceed without the token.

根据 account 状态分支；仅当仓库和对话中无法确定状态时才询问：

已有 Traceway account：“打开
```
<instance>/setup
```
（Traceway Cloud：https://cloud.tracewayapp.com/setup）。如果出现提示，请登录；页面会显示一个以
```
tws_
```
开头的 setup token。请将其粘贴到这里，并保持页面打开。”该 token 有效期为 6 小时；页面有 Generate New Token 按钮。
还没有 account：“打开
```
<instance>/register
```
（Traceway Cloud：https://cloud.tracewayapp.com/register）。步骤 1 会创建你的 account 和 organization。在步骤 2 中，保持选择 ‘AI’；页面会显示一个以
```
tws_
```
开头的 setup token。请将其粘贴到这里并保持页面打开：我提出的方案会显示在页面上供你批准，批准后项目会立即出现。”

在这条路径上，不要让用户在 Web UI 中创建项目，也不要在没有 token 的情况下继续。

3b. Write the plan file

3b. 编写计划文件

Write

traceway-setup-plan.json

from the confirmed map, one entry per project:

json

{
  "projects": [
    {"name": "Product Backend", "framework": "opentelemetry",
     "envFile": "backend/.env", "envVar": "TRACEWAY_BACKEND_TOKEN"},
    {"name": "Product Web", "framework": "svelte",
     "envFile": "frontend/.env", "envVar": "PUBLIC_TRACEWAY_WEB_CONNECTION_STRING",
     "envFormat": "connectionString",
     "deployment": {"platform": "Vercel",
       "instructions": "vercel env add PUBLIC_TRACEWAY_WEB_CONNECTION_STRING production\n# paste: <token>"}}
  ]
}

Rules:

framework

is one of the nine values from Step 2; every

envFile

must be untracked (create it and confirm it is gitignored first);

envVar

follows the credential-naming rules;

deployment.instructions

uses the literal

<token>

placeholder, never a real value.

根据确认后的映射编写

traceway-setup-plan.json

，每个项目对应一个条目：

json

{
  "projects": [
    {"name": "Product Backend", "framework": "opentelemetry",
     "envFile": "backend/.env", "envVar": "TRACEWAY_BACKEND_TOKEN"},
    {"name": "Product Web", "framework": "svelte",
     "envFile": "frontend/.env", "envVar": "PUBLIC_TRACEWAY_WEB_CONNECTION_STRING",
     "envFormat": "connectionString",
     "deployment": {"platform": "Vercel",
       "instructions": "vercel env add PUBLIC_TRACEWAY_WEB_CONNECTION_STRING production\n# paste: <token>"}}
  ]
}

规则：

framework

必须是步骤 2 中的九种值之一；每个

envFile

都必须未纳入版本控制（先创建该文件并确认已被 gitignore）；

envVar

遵循凭据命名规则；

deployment.instructions

使用字面占位符

<token>

，绝不使用真实值。

3c. Submit the plan and wait for approval (curl)

3c. 提交计划并等待批准（curl）

Use

curl

and

jq

directly for this step. Do NOT install the

traceway

CLI for it; nothing gets installed on this path. (Only if a CLI new enough to have

setup apply

is already present is

printf '%s' "$TRACEWAY_SETUP_TOKEN" | traceway setup apply --url "$TRACEWAY_URL" --plan traceway-setup-plan.json --token-stdin

an equivalent one-step alternative.) If

jq

is unavailable and cannot be installed, use the manual fallback (3e).

Export the credentials first; setup tokens may transit chat, so this is fine:

bash

export TRACEWAY_URL="<instance>"          # no trailing slash
export TRACEWAY_SETUP_TOKEN="tws_..."

Validate the token and show the organization (this response carries project names only, safe to display):

bash

curl -s -w '\nHTTP %{http_code}\n' -H "Authorization: Bearer $TRACEWAY_SETUP_TOKEN" \
  "$TRACEWAY_URL/api/setup/session"

Submit the plan as a draft:

bash

curl -s -w '\nHTTP %{http_code}\n' -X PUT \
  -H "Authorization: Bearer $TRACEWAY_SETUP_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @traceway-setup-plan.json "$TRACEWAY_URL/api/setup/plan"

200 {"status":"pending"}

means the draft is up; tell the user: "Review the proposal on the Traceway page you have open and press Approve Setup." A

is a validation message: fix the plan and resubmit. A

means the token is invalid or expired: ask the user for a fresh one from

<instance>/setup

Then wait for the decision with the script below. The script exists because the decision response carries the ingest tokens: values must flow API to env file without ever reaching stdout, your context, or the chat. Write it to

traceway-setup-wait.sh

exactly as given and run

sh traceway-setup-wait.sh

. Never fetch

GET /api/setup/plan

directly, and never read the env files it writes.

#!/bin/sh

此步骤直接使用

curl

和

jq

。不要为此安装

traceway

CLI；这条路径上不会安装任何东西。（仅当已经安装了足够新的、支持

setup apply

的 CLI 时，才可以将

printf '%s' "$TRACEWAY_SETUP_TOKEN" | traceway setup apply --url "$TRACEWAY_URL" --plan traceway-setup-plan.json --token-stdin

作为等效的单步替代方案。）如果无法使用且不能安装

jq

，使用手动回退方案（3e）。

先导出凭据；setup token 可以通过聊天传输，因此这样做是安全的：

bash

export TRACEWAY_URL="<instance>"          # no trailing slash
export TRACEWAY_SETUP_TOKEN="tws_..."

验证 token 并显示 organization（该响应仅包含项目名称，可以安全显示）：

bash

curl -s -w '\\nHTTP %{http_code}\\n' -H "Authorization: Bearer $TRACEWAY_SETUP_TOKEN" \\
  "$TRACEWAY_URL/api/setup/session"

将计划作为 draft 提交：

bash

curl -s -w '\\nHTTP %{http_code}\\n' -X PUT \\
  -H "Authorization: Bearer $TRACEWAY_SETUP_TOKEN" -H 'Content-Type: application/json' \\
  --data-binary @traceway-setup-plan.json "$TRACEWAY_URL/api/setup/plan"

200 {"status":"pending"}

表示 draft 已上传；告知用户：“请在你已打开的 Traceway 页面上审核方案，然后点击 Approve Setup。”

表示验证消息：修复计划后重新提交。

表示 token 无效或已过期：要求用户从

<instance>/setup

获取新 token。

然后使用以下脚本等待决定。之所以使用该脚本，是因为决定响应会携带 ingest token：值必须从 API 直接流入 env 文件，绝不能出现在 stdout、上下文或聊天中。按原样将其写入

traceway-setup-wait.sh

，并运行

sh traceway-setup-wait.sh

。绝不直接请求

GET /api/setup/plan

，也绝不读取它写入的 env 文件。

#!/bin/sh

Waits for the setup decision, then writes each ingest token into the env

file named by the plan. Prints statuses and variable names only.

set -eu PLAN=${1:-traceway-setup-plan.json} AUTH="Authorization: Bearer ${TRACEWAY_SETUP_TOKEN:?}" URL=${TRACEWAY_URL:?} deadline=$(($(date +%s) + 1800)) while :; do resp=$(curl -s -H "$AUTH" "$URL/api/setup/plan") status=$(printf '%s' "$resp" | jq -r '.status // "error"') case "$status" in approved) break ;; rejected) echo "rejected: $(printf '%s' "$resp" | jq -r '.reason // "(no reason given)"')" exit 2 ;; pending|none) ;; *) echo "unexpected response, the setup token may have expired"; exit 1 ;; esac if [ "$(date +%s)" -ge "$deadline" ]; then echo "timed out waiting for approval; rerun when the user is ready" exit 3 fi sleep 3 done i=0 n=$(jq '.projects | length' "$PLAN") while [ "$i" -lt "$n" ]; do name=$(jq -r ".projects[$i].name" "$PLAN") envfile=$(jq -r ".projects[$i].envFile // empty" "$PLAN") envvar=$(jq -r ".projects[$i].envVar // empty" "$PLAN") format=$(jq -r ".projects[$i].envFormat // "token"" "$PLAN") pstatus=$(printf '%s' "$resp" | jq -r --arg n "$name"
'[.projects[] | select(.name == $n)][0].status // "missing"') if [ "$pstatus" = missing ]; then echo "$name: missing from the approved plan" i=$((i + 1)); continue fi if [ -n "$envfile" ] && [ -n "$envvar" ]; then value=$(printf '%s' "$resp" | jq -r --arg n "$name" --arg f "$format"
'[.projects[] | select(.name == $n)][0] | if $f == "connectionString" then .token + "@" + (.backendUrl | sub("/+$"; "")) + "/api/report" else .token end') dir=$(dirname "$envfile"); mkdir -p "$dir" tmp=$(mktemp "$dir/.tmp-env-XXXXXX") { [ -f "$envfile" ] && grep -v "^${envvar}=" "$envfile" > "$tmp"; } || true printf '%s=%s\n' "$envvar" "$value" >> "$tmp" mv "$tmp" "$envfile" echo "$name: $pstatus, wrote $envvar to $envfile" else echo "$name: $pstatus" fi i=$((i + 1)) done echo "done: deployment credentials, if any, are shown on the Traceway page the user has open"


Env files come out mode 0600 via mktemp. Failure handling:

- **Rejected (exit 2)**: the script prints the user's rejection reason. Revise the map with the user, update the plan file, submit again (a new PUT replaces the pending draft), and rerun the wait script. Already-approved projects are matched by name, never duplicated.
- **Expired or invalid token (401 / exit 1)**: ask the user for a fresh token from `<instance>/setup`, re-export it, resubmit, rerun.
- **Timeout (exit 3)**: resubmit and rerun when the user is ready; it is safe.

Delete the plan file and `traceway-setup-wait.sh` after a successful apply; they hold no secrets but they are setup litter.

set -eu PLAN=${1:-traceway-setup-plan.json} AUTH="Authorization: Bearer ${TRACEWAY_SETUP_TOKEN:?}" URL=${TRACEWAY_URL:?} deadline=$(($(date +%s) + 1800)) while :; do resp=$(curl -s -H "$AUTH" "$URL/api/setup/plan") status=$(printf '%s' "$resp" | jq -r '.status // "error"') case "$status" in approved) break ;; rejected) echo "rejected: $(printf '%s' "$resp" | jq -r '.reason // "(no reason given)"')" exit 2 ;; pending|none) ;; *) echo "unexpected response, the setup token may have expired"; exit 1 ;; esac if [ "$(date +%s)" -ge "$deadline" ]; then echo "timed out waiting for approval; rerun when the user is ready" exit 3 fi sleep 3 done i=0 n=$(jq '.projects | length' "$PLAN") while [ "$i" -lt "$n" ]; do name=$(jq -r ".projects[$i].name" "$PLAN") envfile=$(jq -r ".projects[$i].envFile // empty" "$PLAN") envvar=$(jq -r ".projects[$i].envVar // empty" "$PLAN") format=$(jq -r ".projects[$i].envFormat // "token"" "$PLAN") pstatus=$(printf '%s' "$resp" | jq -r --arg n "$name" \ '[.projects[] | select(.name == $n)][0].status // "missing"') if [ "$pstatus" = missing ]; then echo "$name: missing from the approved plan" i=$((i + 1)); continue fi if [ -n "$envfile" ] && [ -n "$envvar" ]; then value=$(printf '%s' "$resp" | jq -r --arg n "$name" --arg f "$format" \ '[.projects[] | select(.name == $n)][0] | if $f == "connectionString" then .token + "@" + (.backendUrl | sub("/+$"; "")) + "/api/report" else .token end') dir=$(dirname "$envfile"); mkdir -p "$dir" tmp=$(mktemp "$dir/.tmp-env-XXXXXX") { [ -f "$envfile" ] && grep -v "^${envvar}=" "$envfile" > "$tmp"; } || true printf '%s=%s\n' "$envvar" "$value" >> "$tmp" mv "$tmp" "$envfile" echo "$name: $pstatus, wrote $envvar to $envfile" else echo "$name: $pstatus" fi i=$((i + 1)) done echo "done: deployment credentials, if any, are shown on the Traceway page the user has open"


通过 `mktemp` 生成的 env 文件权限为 0600。失败处理：

- **Rejected（exit 2）**：脚本会打印用户的拒绝原因。与用户一起修改映射，更新计划文件，重新提交（新的 PUT 会替换 pending draft），然后重新运行等待脚本。已批准的项目按名称匹配，绝不会重复创建。
- **Token 过期或无效（401 / exit 1）**：要求用户从 `<instance>/setup` 获取新 token，重新导出，重新提交并重新运行。
- **超时（exit 3）**：用户准备好后重新提交并重新运行即可，操作是安全的。

成功 apply 后，删除计划文件和 `traceway-setup-wait.sh`；它们不包含 secret，但属于临时设置文件。

3d. Confirm and handle deployment credentials

3d. 确认并处理部署凭据

On approval the Traceway page celebrates and lands the user on the new project's dashboard, which doubles as the confirmation that the projects exist. For every project with a

deployment

block, the page first shows a Next Steps panel with the exact command and the real credential value; walk the user through completing it there before they continue, because the setup page is not reachable again once the account has projects. Never relay those values through chat; if a value is needed later, each project's Connection page in the dashboard carries its token.

批准后，Traceway 页面会显示庆祝信息，并进入新项目的 dashboard；这也确认了项目已经存在。对于每个包含

deployment

block 的项目，页面会先显示 Next Steps panel，其中包含准确命令和真实凭据值；在用户继续之前，应引导其在该页面完成操作，因为 account 拥有项目后无法再次访问 setup 页面。绝不要通过聊天转发这些值；如果后续需要某个值，可从 dashboard 中对应项目的 Connection 页面获取其 token。

3e. Manual fallback

3e. 手动回退方案

When the user prefers clicking,

curl

jq

is unavailable, or apply keeps failing, follow

dashboard-project-setup.md

: the user creates each project in the dashboard UI and puts the tokens straight into their env files or secret store. On this path the old rule applies in full: ingest tokens never transit chat.

Upload tokens stay manual on every path: the uploaders read fixed variable names.

traceway-sourcemaps

reads

TRACEWAY_SOURCEMAP_TOKEN

, and

dart run traceway:upload_symbols

and the iOS dSYM script read

TRACEWAY_UPLOAD_TOKEN

(all three also read

TRACEWAY_URL

). Either name the CI secret exactly that, or keep a component-specific secret and pass it explicitly:

bash

traceway-sourcemaps --url "$TRACEWAY_URL" --token "$TRACEWAY_WEB_UPLOAD_TOKEN" --directory ./dist

Inventing a name like

TRACEWAY_WEB_UPLOAD_TOKEN

and then calling the uploader with no

--token

fails at release time, not at setup time, so make the choice explicit in the CI step. Upload tokens are generated per project from Connection -> Source Maps or Symbol Upload in the dashboard.

当用户希望手动点击操作、无法使用

curl

或

jq

，或者 apply 持续失败时，按照

dashboard-project-setup.md

操作：用户在 dashboard UI 中创建各个项目，并将 token 直接写入 env 文件或 secret store。在这条路径上，完整适用之前的规则：ingest token 绝不通过聊天传输。

所有路径中的 upload token 都必须手动处理，uploader 读取固定变量名。

traceway-sourcemaps

读取

TRACEWAY_SOURCEMAP_TOKEN

，

dart run traceway:upload_symbols

和 iOS dSYM script 读取

TRACEWAY_UPLOAD_TOKEN

（三者也都会读取

TRACEWAY_URL

）。要么将 CI secret 精确命名为该名称，要么保留组件专用 secret 并显式传入：

bash

traceway-sourcemaps --url "$TRACEWAY_URL" --token "$TRACEWAY_WEB_UPLOAD_TOKEN" --directory ./dist

如果自行创建

TRACEWAY_WEB_UPLOAD_TOKEN

一类名称，却在调用 uploader 时不传

--token

，错误只会在发布时出现，而不会在设置时出现，因此必须在 CI 步骤中明确选择。Upload token 在 dashboard 的 Connection -> Source Maps 或 Symbol Upload 中按项目生成。

Integration Paths

集成路径

Pick the path by project type, and pick the project type from the "Analyze the Architecture" findings, never from the framework name alone (a Next.js repo can be a full-stack app or just the frontend of a separate backend). Per path, this is not negotiable per framework; it is how Traceway is designed to receive data:

Project type	Path
Backend (any language)	OpenTelemetry, exporting OTLP/HTTP to `<instance>/api/otel/v1/*` . Always, including Go.
Frontend (browser SPA, or a JS meta-framework running frontend-only in production)	Traceway `@tracewayapp/<framework>` SDK + bundler plugin + source map upload (see "Frontend and Mobile" below).
Full-stack JS (Next.js, SvelteKit, Remix, actually serving its API/SSR in production per "Analyze the Architecture")	BOTH sides, each under its own Traceway project: server side via OpenTelemetry AND browser side via the frontend SDK.
Mobile (Flutter, React Native, Android, native Swift iOS)	The Traceway platform SDK. Never OTel. Sole exception: a non-Swift iOS/Apple app has no native SDK, so it uses an OTel library (e.g. Honeycomb) exporting to Traceway like a backend (see "Frontend and Mobile").

The rules every backend integration must satisfy, and the table of what each span becomes, are in Step 4 where they are applied.

根据项目类型选择路径，并根据“分析架构”中的检测结果确定项目类型，不能只根据 framework 名称判断（Next.js 仓库可能是全栈应用，也可能只是独立后端的 frontend）。每条路径都不按 framework 灵活调整；这是 Traceway 接收数据的设计方式：

项目类型	路径
Backend（任意语言）	OpenTelemetry，通过 OTLP/HTTP 导出到 `<instance>/api/otel/v1/*` 。始终如此，包括 Go。
Frontend（browser SPA，或生产环境仅运行 frontend 的 JS meta-framework）	Traceway `@tracewayapp/<framework>` SDK + bundler plugin + source map 上传（参见下方“前端与移动端”）。
Full-stack JS（Next.js、SvelteKit、Remix，且根据“分析架构”确认其 framework server 确实在生产环境提供 API/SSR）	同时集成两端，并分别使用独立的 Traceway 项目：server 端通过 OpenTelemetry，browser 端通过 frontend SDK。
Mobile（Flutter、React Native、Android、原生 Swift iOS）	Traceway platform SDK，绝不使用 OTel。唯一例外是非 Swift iOS/Apple app 没有原生 SDK，因此使用 OTel library（如 Honeycomb），像 backend 一样导出到 Traceway（参见“前端与移动端”）。

所有 backend integration 必须满足的规则，以及每个 span 的分类结果，都在实际应用这些规则的步骤 4 中。

Step 4: Backend OTel Setup

步骤 4：Backend OTel 设置

The same shape in every language:

Install the language's OpenTelemetry SDK plus the auto-instrumentation for the web framework and database clients.
Point the OTLP/HTTP exporter at Traceway with the project token as a Bearer header.
Set
```
service.name
```
(becomes the Server Name in Traceway) and
```
service.version
```
(enables release comparison) on the resource.
Verify endpoint grouping before anything else.

所有语言都采用相同结构：

安装该语言的 OpenTelemetry SDK，以及 Web framework 和数据库 client 的 auto-instrumentation。
将 OTLP/HTTP exporter 指向 Traceway，并通过 Bearer header 携带项目 token。
在 resource 上设置
```
service.name
```
（对应 Traceway 中的 Server Name）和
```
service.version
```
（用于版本比较）。
首先验证 endpoint 分组。

Three rules that are not negotiable

三条不可协商的规则

Endpoints MUST arrive parametrized.
```
http.route
```
must be the route pattern (
```
/api/users/:id
```
), never the concrete URL. Traceway uses the value as-is, but only when it starts with
```
/
```
: a route name like
```
app_user_show
```
is discarded exactly like a missing value. With no usable route it falls back to
```
url.path
```
, and the Endpoints page explodes into one row per unique URL.
Background work MUST use
SpanKind.CONSUMER
. A root span with the default
```
INTERNAL
```
kind and no HTTP attributes is silently dropped (exceptions recorded on it still reach Issues, but the task run itself is lost).
The exporter MUST use an OpenTelemetry project's token. If OTLP arrives with a browser project's token (framework React, Svelte, Vue.js, jQuery, or React Native), Traceway keeps only the Issues and discards every endpoint, task, child span, and AI trace. The symptom is "errors appear but the Endpoints page is empty", and the cause is almost always two projects whose tokens got swapped.

Endpoint 必须参数化。
```
http.route
```
必须是 route pattern（
```
/api/users/:id
```
），绝不能是具体 URL。Traceway 会原样使用该值，但只有以
```
/
```
开头时才有效：像
```
app_user_show
```
这样的 route name 会像缺失值一样被丢弃。没有可用 route 时，它会回退到
```
url.path
```
，导致 Endpoints 页面为每个唯一 URL 生成一行。
后台工作必须使用
SpanKind.CONSUMER
。使用默认
```
INTERNAL
```
kind 且没有 HTTP attribute 的 root span 会被静默丢弃（记录在其上的 exception 仍会进入 Issues，但任务执行本身会丢失）。
Exporter 必须使用 OpenTelemetry 项目的 token。 如果 OTLP 使用 browser 项目的 token（framework 为 React、Svelte、Vue.js、jQuery 或 React Native），Traceway 只会保留 Issues，并丢弃所有 endpoint、task、child span 和 AI trace。症状是“错误出现了，但 Endpoints 页面为空”，原因几乎总是两个项目的 token 被交换了。

How Traceway classifies spans

Traceway 如何分类 span

The rules are evaluated in this order and the first match wins.

#	Span	Condition	Becomes
1	Any span	`SpanKind = INTERNAL` and carries `exception.*` attributes	Issue. Never promoted, even with HTTP or `gen_ai.*` attributes present. A child span keeps its ordinary Span row, a root span gets only the Issue
2	Root span, or a span whose parent is not in the same export batch	`SpanKind = SERVER` or `INTERNAL` with HTTP attributes	Endpoint
3	Any span	`SpanKind = CONSUMER`	Task
4	Root span	`SpanKind = INTERNAL` with a `console.command` attribute	Task (CLI command)
5	Any span	Has any `gen_ai.*` attribute	AI Trace
6	Non-root span	Has a parent span id	Span (child)
7	Root span	Nothing above matched	Dropped (exceptions recorded on it still become Issues, unlinked)

Because the order is fixed, a

CONSUMER

span carrying

gen_ai.*

is a Task, and a

SERVER

request span carrying

gen_ai.*

is an Endpoint. Put the model call on its own child span (Step 6).

Two more rules that do not depend on span kind:

An
```
exception
```
event, or
```
exception.*
```
attributes, on any span produces an Issue, whatever the span itself became.
An endpoint that returns 404 with no real route matched (
```
http.route
```
missing, or a catch-all like
```
/
```
,
```
/*
```
) is renamed to the literal endpoint
```
UNMATCHED
```
, so bot scans and typo'd URLs collapse into one row. A concrete matched route returning 404 keeps its own name.

For the exact rules, endpoint naming, metric conversion, and the remaining quirks, read

data-model.md

in this skill directory. It is the authoritative reference.

规则按以下顺序评估，首个匹配项生效。

#	Span	条件	结果
1	任意 span	`SpanKind = INTERNAL` 且包含 `exception.*` attribute	Issue。即使同时存在 HTTP 或 `gen_ai.*` attribute，也不会提升为其他类型。Child span 保留普通 Span 行，root span 只生成 Issue
2	Root span，或 parent 不在同一 export batch 中的 span	`SpanKind = SERVER` ，或带 HTTP attribute 的 `INTERNAL`	Endpoint
3	任意 span	`SpanKind = CONSUMER`	Task
4	Root span	带 `console.command` attribute 的 `INTERNAL`	Task（CLI command）
5	任意 span	包含任意 `gen_ai.*` attribute	AI Trace
6	Non-root span	包含 parent span id	Span（child）
7	Root span	未匹配上述任何规则	丢弃（记录在其上的 exception 仍会生成无关联的 Issue）

由于顺序固定，带有

gen_ai.*

的

CONSUMER

span 是 Task，而带有

gen_ai.*

的

SERVER

request span 是 Endpoint。将 model call 放在独立的 child span 中（步骤 6）。

另外两条不依赖 span kind 的规则：

任意 span 上的
```
exception
```
event 或
```
exception.*
```
attribute 都会生成 Issue，无论该 span 本身被归为什么类型。
返回 404 且没有匹配到真实 route 的 endpoint（缺少
```
http.route
```
，或使用
```
/
```
、
```
/*
```
一类 catch-all）会重命名为字面 endpoint
```
UNMATCHED
```
，从而将 bot scan 和拼写错误的 URL 合并为一行。匹配到真实 route 后返回 404 的 endpoint 仍保留自己的名称。

准确的规则、endpoint 命名、metric 转换和其他细节，参见此 skill 目录中的

data-model.md

。它是权威参考。

Exporter configuration

Exporter 配置

Where the SDK supports the standard env vars, prefer them; they work identically across languages:

bash

OTEL_SERVICE_NAME=my-service
OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3   # there is no OTEL_SERVICE_VERSION variable
OTEL_EXPORTER_OTLP_ENDPOINT=https://<instance>/api/otel
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf        # required, several SDKs default to gRPC
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <project-token>"
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp

Two of those lines are load-bearing in a way that fails silently:

OTEL_EXPORTER_OTLP_PROTOCOL
is not optional. Left unset, the Python SDK and the Java agent resolve
```
otlp
```
to gRPC, and Traceway has no gRPC listener. The app starts, serves traffic, exits 0, prints no warning, and every export is lost. (PHP is the one exception to the value: it needs
```
http/json
```
.)
There is no
OTEL_SERVICE_VERSION
.
```
service.version
```
only reaches Traceway through
```
OTEL_RESOURCE_ATTRIBUTES
```
. Without it, every endpoint row comes back with an empty App Version and release comparison does nothing.

SDKs append

/v1/traces

/v1/metrics

/v1/logs

to the endpoint automatically, so set the base URL only. A full signal path in

OTEL_EXPORTER_OTLP_ENDPOINT

produces

/v1/traces/v1/traces

, and the signal-specific variables (

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

) are used verbatim with nothing appended. When configuring in code instead, the full URLs are

https://<instance>/api/otel/v1/traces

(and

/v1/metrics

/v1/logs

) with header

Authorization: Bearer <project-token>

When Step 3's apply script wrote the env files, the plan's variables already hold real values locally, so wire the exporter to exactly those names (e.g.

Authorization=Bearer ${TRACEWAY_BACKEND_TOKEN}

) and run live verification immediately. The script writes only each project's one plan variable: companion variables the integration reads, like

TRACEWAY_URL

for the instance URL, are yours to add to the same env file now. On the manual fallback the user populates the variables first.

Constraints: OTLP/HTTP only (protobuf or JSON). OTLP/gRPC is not supported, there is no listener on port 4317.

Content-Encoding: gzip

is fine. The body is capped at 10 MB after decompression, and an oversized batch is rejected outright with

and

{"error":"request body exceeds the 10MB limit"}

. Nothing is ingested partially. A wrong or missing token answers

, and any other path answers

. All three are invisible from the application: most SDKs log exporter failures at debug level only, so when nothing arrives, turn the SDK's own diagnostic logging on first.

在 SDK 支持标准 env var 时，优先使用这些 env var；它们在各语言中的行为一致：

bash

OTEL_SERVICE_NAME=my-service
OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3   # there is no OTEL_SERVICE_VERSION variable
OTEL_EXPORTER_OTLP_ENDPOINT=https://<instance>/api/otel
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf        # required, several SDKs default to gRPC
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <project-token>"
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp

其中两行会以静默失败的方式影响整个流程：

OTEL_EXPORTER_OTLP_PROTOCOL
不是可选项。如果未设置，Python SDK 和 Java agent 会将
```
otlp
```
解析为 gRPC，而 Traceway 没有 gRPC listener。应用会启动、处理流量、以 0 退出，不打印任何警告，每次 export 都会丢失。（PHP 是该值的唯一例外，它需要使用
```
http/json
```
。）
不存在
OTEL_SERVICE_VERSION
。
```
service.version
```
只能通过
```
OTEL_RESOURCE_ATTRIBUTES
```
到达 Traceway。如果不设置，每个 endpoint row 的 App Version 都会为空，版本比较也不会生效。

SDK 会自动在 endpoint 后追加

/v1/traces

、

/v1/metrics

、

/v1/logs

，因此只设置 base URL。将完整 signal path 写入

OTEL_EXPORTER_OTLP_ENDPOINT

会产生

/v1/traces/v1/traces

；而 signal-specific variable（

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

）会原样使用，不会追加路径。通过代码配置时，完整 URL 为

https://<instance>/api/otel/v1/traces

（以及

/v1/metrics

、

/v1/logs

），header 为

Authorization: Bearer <project-token>

。

当步骤 3 的 apply script 已将 env 文件写入真实值时，计划中的变量在本地已经包含真实值，因此应将 exporter 精确连接到这些变量名（例如

Authorization=Bearer ${TRACEWAY_BACKEND_TOKEN}

），并立即执行实时验证。Script 只写入每个项目的一个计划变量；integration 读取的配套变量（例如 instance URL 对应的

TRACEWAY_URL

）需要由你添加到同一个 env 文件中。在手动回退路径中，用户需先填充这些变量。

限制：仅支持 OTLP/HTTP（protobuf 或 JSON）。不支持 OTLP/gRPC，4317 端口没有 listener。可以使用

Content-Encoding: gzip

。解压后的 body 上限为 10 MB，超出限制的 batch 会被直接以

拒绝，并返回

{"error":"request body exceeds the 10MB limit"}

。不会进行部分摄取。Token 错误或缺失时返回

，其他无效路径返回

。这三种情况在 application 层都不可见：多数 SDK 只在 debug level 记录 exporter 失败，因此当没有数据到达时，应先启用 SDK 自身的 diagnostic logging。

Node.js example

Node.js 示例

bash

npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \
  @opentelemetry/instrumentation @opentelemetry/api @opentelemetry/sdk-metrics \
  @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http

Declare

@opentelemetry/api

yourself even though it also arrives transitively. Relying on hoisting breaks under pnpm's strict

node_modules

and under Yarn PnP.

Create

instrumentation.mjs

at the project root and load it before the app:

node --import ./instrumentation.mjs server.js

. Use the

.mjs

extension. A

.js

file holding

import

syntax fails to load in a CommonJS project, which is what most projects still are.

javascript

import { register } from "node:module";
register("@opentelemetry/instrumentation/hook.mjs", import.meta.url);

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";

const url = process.env.TRACEWAY_URL;
const headers = { Authorization: `Bearer ${process.env.TRACEWAY_BACKEND_TOKEN}` };

const sdk = new NodeSDK({
  serviceName: process.env.OTEL_SERVICE_NAME ?? "my-service",
  traceExporter: new OTLPTraceExporter({ url: `${url}/api/otel/v1/traces`, headers }),
  metricReaders: [
    new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter({ url: `${url}/api/otel/v1/metrics`, headers }),
      exportIntervalMillis: 30_000,
    }),
  ],
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

Three parts of that snippet are load-bearing:

The two
register
lines install the ESM loader hook. Without them an ESM app (
```
"type": "module"
```
,
```
import express from "express"
```
) still gets HTTP spans but no
```
http.route
```
, so every URL becomes its own endpoint row. A CommonJS app (
```
require("express")
```
) is patched without the hook, and the lines are harmless there, so keep them either way.
serviceName
becomes the Server Name in Traceway. Leave it out and every span reports
```
unknown_service:node
```
. For release comparison also set
```
OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3
```
.
metricReaders
is a list. The older singular
```
metricReader
```
option is deprecated.

Auto-instrumentation covers Express routes (sets

http.route

), status codes, errors, and database clients (

pg

mysql2

mongodb

ioredis

). SQLite and custom business logic need manual

tracer.startActiveSpan()

child spans.

bash

npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \\
  @opentelemetry/instrumentation @opentelemetry/api @opentelemetry/sdk-metrics \\
  @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http

即使

@opentelemetry/api

会作为传递依赖安装，也应显式声明。依赖 hoisting 在 pnpm 的严格

node_modules

和 Yarn PnP 下都会失效。

在项目根目录创建

instrumentation.mjs

，并在 app 之前加载：

node --import ./instrumentation.mjs server.js

。使用

.mjs

扩展名。在 CommonJS 项目中，包含

import

语法的

.js

文件无法加载，而目前大多数项目仍使用 CommonJS。

javascript

import { register } from "node:module";
register("@opentelemetry/instrumentation/hook.mjs", import.meta.url);

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";

const url = process.env.TRACEWAY_URL;
const headers = { Authorization: `Bearer ${process.env.TRACEWAY_BACKEND_TOKEN}` };

const sdk = new NodeSDK({
  serviceName: process.env.OTEL_SERVICE_NAME ?? "my-service",
  traceExporter: new OTLPTraceExporter({ url: `${url}/api/otel/v1/traces`, headers }),
  metricReaders: [
    new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter({ url: `${url}/api/otel/v1/metrics`, headers }),
      exportIntervalMillis: 30_000,
    }),
  ],
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

该代码片段中有三部分是关键配置：

两行
register
用于安装 ESM loader hook。如果缺少它们，ESM app（
```
"type": "module"
```
、
```
import express from "express"
```
）仍会产生 HTTP span，但没有
```
http.route
```
，导致每个 URL 都成为独立的 endpoint row。CommonJS app（
```
require("express"
```
）无需 hook 也会被 patch，因此两种情况下都应保留这两行。
serviceName
对应 Traceway 中的 Server Name。如果不设置，所有 span 都会上报
```
unknown_service:node
```
。若要使用版本比较，还要设置
```
OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3
```
。
metricReaders
是一个列表。旧的单数
```
metricReader
```
选项已弃用。

Auto-instrumentation 覆盖 Express route（设置

http.route

）、status code、error 和数据库 client（

pg

、

mysql2

、

mongodb

、

ioredis

）。SQLite 和自定义业务逻辑需要使用

tracer.startActiveSpan()

手动创建 child span。

Next.js server exception

Next.js server 例外情况

Next.js must not use the generic

instrumentation.mjs

preload above,

node --import

, or

NODE_OPTIONS

. Next.js creates its own incoming request root span with the matched

http.route

; preloading the generic Node HTTP instrumentation creates a competing root named from the literal URL, so

/api/users/1

and

/api/users/2

become separate endpoints.

For a Next.js server, create a minimal

instrumentation.ts

hook and put the SDK in a separate

instrumentation.node.ts

. Next.js compiles the hook for both Node and Edge; importing OTel packages directly in the hook, even with dynamic

import()

calls after a runtime guard, can make the development Edge compilation resolve Node built-ins and fail. The wrapper must conditionally import only the Node module:

typescript

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./instrumentation.node");
  }
}

Keep every Node-only import and the SDK startup in the sibling module:

typescript

import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { NodeSDK } from "@opentelemetry/sdk-node";

(Error as unknown as { prepareStackTrace?: unknown }).prepareStackTrace = undefined;

const instance = process.env.TRACEWAY_URL!.replace(/\/+$/, "");
const base = `${instance}/api/otel`;
const headers = { Authorization: `Bearer ${process.env.TRACEWAY_BACKEND_TOKEN}` };

new NodeSDK({
  resource: resourceFromAttributes({
    "service.name": process.env.OTEL_SERVICE_NAME ?? "nextjs-server",
    "service.version": process.env.APP_VERSION ?? "development",
  }),
  traceExporter: new OTLPTraceExporter({ url: `${base}/v1/traces`, headers }),
  metricReaders: [
    new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter({ url: `${base}/v1/metrics`, headers }),
      exportIntervalMillis: 30_000,
    }),
  ],
  logRecordProcessors: [
    new BatchLogRecordProcessor({
      exporter: new OTLPLogExporter({ url: `${base}/v1/logs`, headers }),
    }),
  ],
  instrumentations: [getNodeAutoInstrumentations()],
}).start();

Install the log exporter and SDK packages in addition to the generic Node dependencies:

@opentelemetry/exporter-logs-otlp-http

@opentelemetry/sdk-logs

@opentelemetry/api-logs

, and

@opentelemetry/resources

. Next.js versions before 15 also need

experimental.instrumentationHook: true

. Full setup and verification: https://docs.tracewayapp.com/client/otel/nextjs

Resetting

Error.prepareStackTrace

instrumentation.node.ts

lets Node apply source maps instead of leaving server Issues pointed at minified Next chunks. Production must also start with

NODE_OPTIONS=--enable-source-maps

, and the build must emit

.next/server/**/*.js.map

; verify both rather than assuming readable server stacks. If the webpack build omits them, add

experimental: { serverSourceMaps: true }

next.config

. Also list

@opentelemetry/auto-instrumentations-node

serverExternalPackages

so Next does not bundle the instrumentation registry or warn about its optional transports.

Next.js 不得使用上述通用

instrumentation.mjs

preload、

node --import

或

NODE_OPTIONS

。Next.js 会创建自己的 incoming request root span，并带上匹配后的

http.route

；预加载通用 Node HTTP instrumentation 会创建另一个以实际 URL 命名的竞争 root span，导致

/api/users/1

和

/api/users/2

成为不同 endpoint。

对于 Next.js server，创建一个精简的

instrumentation.ts

hook，并将 SDK 放在独立的

instrumentation.node.ts

中。Next.js 会为 Node 和 Edge 编译该 hook；即使在 runtime guard 后使用 dynamic

import()

，直接在 hook 中导入 OTel package 也可能导致开发环境的 Edge compilation 解析 Node built-in 并失败。Wrapper 必须有条件地仅导入 Node module：

typescript

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./instrumentation.node");
  }
}

将所有 Node-only import 和 SDK 启动逻辑保留在同级 module 中：

typescript

import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { NodeSDK } from "@opentelemetry/sdk-node";

(Error as unknown as { prepareStackTrace?: unknown }).prepareStackTrace = undefined;

const instance = process.env.TRACEWAY_URL!.replace(/\\/+$/, "");
const base = `${instance}/api/otel`;
const headers = { Authorization: `Bearer ${process.env.TRACEWAY_BACKEND_TOKEN}` };

new NodeSDK({
  resource: resourceFromAttributes({
    "service.name": process.env.OTEL_SERVICE_NAME ?? "nextjs-server",
    "service.version": process.env.APP_VERSION ?? "development",
  }),
  traceExporter: new OTLPTraceExporter({ url: `${base}/v1/traces`, headers }),
  metricReaders: [
    new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter({ url: `${base}/v1/metrics`, headers }),
      exportIntervalMillis: 30_000,
    }),
  ],
  logRecordProcessors: [
    new BatchLogRecordProcessor({
      exporter: new OTLPLogExporter({ url: `${base}/v1/logs`, headers }),
    }),
  ],
  instrumentations: [getNodeAutoInstrumentations()],
}).start();

除通用 Node 依赖外，还要安装 log exporter 和 SDK package：

@opentelemetry/exporter-logs-otlp-http

、

@opentelemetry/sdk-logs

、

@opentelemetry/api-logs

和

@opentelemetry/resources

。15 之前的 Next.js 版本还需要

experimental.instrumentationHook: true

。完整设置与验证：https://docs.tracewayapp.com/client/otel/nextjs

在

instrumentation.node.ts

中重置

Error.prepareStackTrace

，可以让 Node 应用 source map，而不是让 server Issue 指向压缩后的 Next chunk。生产环境还必须以

NODE_OPTIONS=--enable-source-maps

启动，并且构建必须生成

.next/server/**/*.js.map

；应同时验证这两点，而不是假设 server stack 一定可读。如果 webpack build 没有生成这些文件，在

next.config

中添加

experimental: { serverSourceMaps: true }

。还要将

@opentelemetry/auto-instrumentations-node

加入

serverExternalPackages

，避免 Next bundle instrumentation registry 或警告其 optional transport。

Per-language notes

各语言注意事项

Go: use the framework's OTel middleware.

go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin

github.com/riandyrn/otelchi

(a community package, and pass

otelchi.WithChiRoutes(r)

or it reports raw URLs),

github.com/gofiber/contrib/otelfiber/v2

. All three set

http.route

from the matched route pattern. Exporter:

otlptracehttp.WithEndpointURL(...)

WithHeaders

. Two Go-only traps:

Set the propagator. Go's global propagator is a no-op by default, so

traceparent

is never sent or read and cross-service traces never link. One line, right after

otel.SetTracerProvider(tp)

otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
    propagation.TraceContext{}, propagation.Baggage{},
))

stdlib
net/http
does not report its route.

otelhttp

reads the route from

r.Pattern

, which

ServeMux

fills in only after it has matched, so the usual top-level

otelhttp.NewHandler(mux, "server")

records no

http.route

at all and every URL becomes its own endpoint row. Either wrap each registered handler, which puts the span start inside the mux:

mux.Handle("GET /api/users/{id}", otelhttp.NewHandler(usersHandler, "users"))

or keep the single top-level wrap and stamp the route yourself:

// imports: strings, go.opentelemetry.io/otel/trace,
//          semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
func withRoute(mux *http.ServeMux) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if _, pattern := mux.Handler(r); pattern != "" {
            if i := strings.IndexByte(pattern, '/'); i >= 0 {
                route := pattern[i:] // drop the "GET " prefix, http.route must start with "/"
                trace.SpanFromContext(r.Context()).SetAttributes(semconv.HTTPRoute(route))
            }
        }
        mux.ServeHTTP(w, r)
    })
}

handler := otelhttp.NewHandler(withRoute(mux), "server")

Python:
```
pip install opentelemetry-distro opentelemetry-exporter-otlp
```
, then
```
opentelemetry-bootstrap -a install
```
, then run the app under
```
opentelemetry-instrument
```
with the env vars above (
```
opentelemetry-instrument uvicorn app:app
```
,
```
opentelemetry-instrument gunicorn wsgi:app
```
,
```
opentelemetry-instrument python worker.py
```
). Starting the server without that prefix sends nothing. FastAPI and Flask instrumentation sets
```
http.route
```
correctly with zero application code, in the framework's own syntax (
```
GET /users/{user_id}
```
,
```
GET /orders/<order_id>
```
), and both frameworks already answer
```
500
```
on an unhandled exception, so the endpoint status and the Issue line up without extra work. Three Python-only gotchas:
- Logs need two more variables.
```
OTEL_LOGS_EXPORTER=otlp
```
  attaches the OTel handler to the root logger, whose level defaults to
```
WARNING
```
  , so every
```
logger.info(...)
```
  is filtered out before the bridge sees it and only WARN and above reach Traceway. Attaching the handler also replaces the root handler list, so the app's own records stop appearing on stdout. Add both:
  bash
```
OTEL_PYTHON_LOG_CORRELATION=true   # restores console output, stamps otelTraceID/otelSpanID
OTEL_PYTHON_LOG_LEVEL=info         # only read alongside the line above
```
```
OTEL_PYTHON_LOG_LEVEL
```
  on its own does nothing. Do not set
```
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
```
  ; on current versions the bridge is already on and that variable switches it to the SDK's deprecated handler.
- Metrics take a minute. The SDK default for
```
OTEL_METRIC_EXPORT_INTERVAL
```
  is 60000 ms, so a correct pipeline looks empty while you are checking it. Set
```
OTEL_METRIC_EXPORT_INTERVAL=10000
```
  during verification.
- Django needs two extra things: export
```
DJANGO_SETTINGS_MODULE
```
  or
```
opentelemetry-instrument
```
  fails to start Django at all, and add the route middleware from the Django guide, because
```
opentelemetry-instrumentation-django
```
  reports
```
http.route
```
  as Django's own pattern (
```
api/users/<int:user_id>/
```
  ), which has no leading
```
/
```
  and is therefore discarded.
Guides: https://docs.tracewayapp.com/client/otel/python and https://docs.tracewayapp.com/client/otel/django
PHP: Laravel via
```
composer require keepsuit/laravel-opentelemetry open-telemetry/exporter-otlp php-http/guzzle7-adapter
```
; Symfony via
```
composer require traceway/opentelemetry-symfony open-telemetry/exporter-otlp php-http/guzzle7-adapter
```
(the stock Symfony auto-instrumentation sets
```
http.route
```
to the route NAME, which Traceway discards; see
```
data-model.md
```
). PHP does not take
```
OTEL_PHP_AUTOLOAD_ENABLED
```
as a plain env var next to the block above. Laravel needs nothing extra, the keepsuit service provider starts the SDK. Symfony starts the SDK through
```
open_telemetry.sdk.autoload_enabled: true
```
in
```
config/packages/open_telemetry.yaml
```
, or through a real process environment variable set in php-fpm, the Dockerfile, or Apache. Never put
```
OTEL_PHP_AUTOLOAD_ENABLED
```
in
```
.env
```
: Dotenv reads it after Composer autoload, the bundle then skips starting the SDK, and every signal silently becomes a no-op. PHP also prefers
```
OTEL_EXPORTER_OTLP_PROTOCOL=http/json
```
, though
```
http/protobuf
```
works too and is only slower without
```
ext-protobuf
```
.
- Symfony workers: never instrument
  messenger:consume
  . The bundle already excludes it.
```
traces.console.excluded_commands
```
  defaults to
```
['messenger:consume', 'messenger:consume-messages']
```
  , and that key is a prototyped array node, so setting it in
```
config/packages/open_telemetry.yaml
```
  REPLACES the default instead of adding to it. If you override it for any reason you MUST re-list both entries. A consumer runs in an endless loop, so its command span never ends, never exports, and swallows every child span for the life of the worker. Excluding the command does not silence the work inside it: the Messenger middleware still emits one CONSUMER span per message, and those are what become Tasks in Traceway. Check what actually resolved with
```
bin/console debug:config open_telemetry traces.console
```
  .
Java / .NET / anything else: the standard OTel agent or SDK with the env vars above works as-is.
Full per-framework docs: https://docs.tracewayapp.com/client/otel

Go：使用 framework 的 OTel middleware：

go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin

、

github.com/riandyrn/otelchi

（社区 package，必须传入

otelchi.WithChiRoutes(r)

，否则会报告原始 URL）、

github.com/gofiber/contrib/otelfiber/v2

。三者都会根据匹配后的 route pattern 设置

http.route

。Exporter：

otlptracehttp.WithEndpointURL(...)

WithHeaders

。Go 有两个独有的陷阱：

设置 propagator。 Go 的 global propagator 默认不做任何事情，因此
```
traceparent
```
不会被发送或读取，cross-service trace 也无法关联。在
```
otel.SetTracerProvider(tp)
```
后立即添加一行：
go
```
otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
    propagation.TraceContext{}, propagation.Baggage{},
))
```

stdlib
net/http
不会报告 route。

otelhttp

从

r.Pattern

读取 route，而

ServeMux

只有在匹配完成后才会填充该值，因此常见的顶层

otelhttp.NewHandler(mux, "server")

不会记录任何

http.route

，每个 URL 都会成为独立的 endpoint row。可以包装每个注册的 handler，让 span 在 mux 内部启动：

mux.Handle("GET /api/users/{id}", otelhttp.NewHandler(usersHandler, "users"))

或保留单个顶层 wrapper，并自行设置 route：

// imports: strings, go.opentelemetry.io/otel/trace,
//          semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
func withRoute(mux *http.ServeMux) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if _, pattern := mux.Handler(r); pattern != "" {
            if i := strings.IndexByte(pattern, '/'); i >= 0 {
                route := pattern[i:] // drop the "GET " prefix, http.route must start with "/"
                trace.SpanFromContext(r.Context()).SetAttributes(semconv.HTTPRoute(route))
            }
        }
        mux.ServeHTTP(w, r)
    })
}

handler := otelhttp.NewHandler(withRoute(mux), "server")

Python：
```
pip install opentelemetry-distro opentelemetry-exporter-otlp
```
，然后运行
```
opentelemetry-bootstrap -a install
```
，再使用上述 env var，通过
```
opentelemetry-instrument
```
启动 app（
```
opentelemetry-instrument uvicorn app:app
```
、
```
opentelemetry-instrument gunicorn wsgi:app
```
、
```
opentelemetry-instrument python worker.py
```
）。不使用此前缀启动 server 不会发送任何数据。FastAPI 和 Flask instrumentation 无需修改 application code 即可正确设置
```
http.route
```
，并使用 framework 自身的语法（
```
GET /users/{user_id}
```
、
```
GET /orders/<order_id>
```
）。两个 framework 在未处理 exception 时都会返回
```
500
```
，因此 endpoint status 和 Issue 无需额外处理即可对应。Python 有三个独有的问题：
- 日志还需要两个变量。
```
OTEL_LOGS_EXPORTER=otlp
```
  会把 OTel handler 附加到 root logger，而 root logger 的默认 level 是
```
WARNING
```
  ，因此所有
```
logger.info(...)
```
  都会在 bridge 看到之前被过滤，只有 WARN 及以上级别能到达 Traceway。附加 handler 还会替换 root handler 列表，导致 app 自身的日志不再出现在 stdout。需要同时添加：
  bash
```
OTEL_PYTHON_LOG_CORRELATION=true   # restores console output, stamps otelTraceID/otelSpanID
OTEL_PYTHON_LOG_LEVEL=info         # only read alongside the line above
```
  单独设置
```
OTEL_PYTHON_LOG_LEVEL
```
  不会产生任何效果。不要设置
```
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
```
  ；当前版本的 bridge 已默认启用，该变量会将其切换到 SDK 已弃用的 handler。
- Metric 需要等待一分钟。 SDK 默认的
```
OTEL_METRIC_EXPORT_INTERVAL
```
  为 60000 ms，因此验证期间正确的 pipeline 可能看起来是空的。验证时将
```
OTEL_METRIC_EXPORT_INTERVAL=10000
```
  。
- Django 需要额外处理两项：导出
```
DJANGO_SETTINGS_MODULE
```
  ，否则
```
opentelemetry-instrument
```
  无法启动 Django；并按照 Django guide 添加 route middleware，因为
```
opentelemetry-instrumentation-django
```
  报告的
```
http.route
```
  是 Django 自身的 pattern（
```
api/users/<int:user_id>/
```
  ），没有前导
```
/
```
  ，因此会被丢弃。
Guides：https://docs.tracewayapp.com/client/otel/python 和 https://docs.tracewayapp.com/client/otel/django
PHP：Laravel 使用
```
composer require keepsuit/laravel-opentelemetry open-telemetry/exporter-otlp php-http/guzzle7-adapter
```
；Symfony 使用
```
composer require traceway/opentelemetry-symfony open-telemetry/exporter-otlp php-http/guzzle7-adapter
```
（Symfony 自带的 auto-instrumentation 会将
```
http.route
```
设置为 route NAME，而 Traceway 会将其丢弃；参见
```
data-model.md
```
）。PHP 不会在上述配置块旁以普通 env var 的形式读取
```
OTEL_PHP_AUTOLOAD_ENABLED
```
。Laravel 无需额外操作，keepsuit service provider 会启动 SDK。Symfony 通过
```
config/packages/open_telemetry.yaml
```
中的
```
open_telemetry.sdk.autoload_enabled: true
```
启动 SDK，或者通过 php-fpm、Dockerfile 或 Apache 中设置的真实 process environment variable 启动。绝不把
```
OTEL_PHP_AUTOLOAD_ENABLED
```
放在
```
.env
```
中：Dotenv 会在 Composer autoload 之后读取它，bundle 随后会跳过 SDK 启动，所有 signal 都会静默变成 no-op。PHP 更推荐使用
```
OTEL_EXPORTER_OTLP_PROTOCOL=http/json
```
，不过
```
http/protobuf
```
也可用，只是在没有
```
ext-protobuf
```
时速度较慢。
- Symfony worker：绝不检测
  messenger:consume
  。 Bundle 已经将其排除。
```
traces.console.excluded_commands
```
  默认值为
```
['messenger:consume', 'messenger:consume-messages']
```
  ，并且该 key 是 prototyped array node，因此设置
```
config/packages/open_telemetry.yaml
```
  会替换默认值，而不是追加。如果出于任何原因覆盖它，则必须重新列出这两项。Consumer 会进入无限循环，因此 command span 永远不会结束、永远不会导出，并会在 worker 整个生命周期中吞掉所有 child span。排除该 command 并不会让内部工作停止：Messenger middleware 仍会为每条 message 发出一个 CONSUMER span，而这些 span 才会成为 Traceway 中的 Task。检查
```
bin/console debug:config open_telemetry traces.console
```
  ，确认实际生效的配置。
Java / .NET / 其他：使用上述 env var 的标准 OTel agent 或 SDK 即可。
各 framework 的完整文档：https://docs.tracewayapp.com/client/otel

Verify endpoint grouping (do this first)

首先验证 endpoint 分组

Hit a parametrized route a few times with different IDs and check the Traceway Endpoints page: you must see ONE row (

GET /api/users/:id

), not one row per ID. If you see raw IDs, the instrumentation is not setting

http.route

; fix that before continuing. Last resort, set it manually in a middleware that knows the matched route pattern (the value must start with

, or it is discarded):

javascript

import { trace } from "@opentelemetry/api";

trace.getActiveSpan()?.setAttribute("http.route", matchedRoutePattern);

使用不同 ID 多次命中参数化 route，然后查看 Traceway Endpoints 页面：必须只出现一行（

GET /api/users/:id

），而不是每个 ID 一行。如果看到原始 ID，说明 instrumentation 没有设置

http.route

；继续之前先修复它。最后的手段是在知道匹配后 route pattern 的 middleware 中手动设置（该值必须以

开头，否则会被丢弃）：

javascript

import { trace } from "@opentelemetry/api";

trace.getActiveSpan()?.setAttribute("http.route", matchedRoutePattern);

Errors

Error

Thrown errors must be recorded as exception events to appear as Issues. Auto-instrumentation handles uncaught errors; for caught-and-handled ones:

javascript

import { trace, SpanStatusCode } from "@opentelemetry/api";

const span = trace.getActiveSpan();
span?.recordException(error);
span?.setStatus({ code: SpanStatusCode.ERROR, message: error.message });

(Go:

span.RecordError(err, trace.WithStackTrace(true))

; the stack trace option is what produces the

exception.stacktrace

attribute.)

Return HTTP 500 when an exception happens. A request that throws or panics must respond with

and set the span status to

ERROR

. Never let it fall through to a

2xx

. The common trap is a recover/panic middleware that reports the exception but lets the response writer keep its default

: Traceway then records the endpoint transaction as a success, so the Endpoints page looks healthy while Issues fills up, and the exception becomes an unlinked island instead of correlating to a failed request (and, with distributed tracing, to the frontend call that triggered it). Always pair "an exception was recorded" with "respond

and set span status

ERROR

". Genuine client errors that are NOT bugs (validation

, auth

, not-found

) keep their real 4xx status and should not be recorded as exceptions in the first place.

Go has a sharper version of the same trap.

otelgin

records the status only after

c.Next()

returns, which never happens during a panic unwind, so an unrecovered panic leaves the endpoint row at status 0 even though Gin's own recovery already returned 500 to the client, and the Issue arrives with a title but no stack trace. Register a recovery middleware after

otelgin.Middleware

so it runs inside the server span:

// imports: fmt, net/http, go.opentelemetry.io/otel/codes, go.opentelemetry.io/otel/trace
func otelRecovery() gin.HandlerFunc {
    return func(c *gin.Context) {
        defer func() {
            if r := recover(); r != nil {
                err, ok := r.(error)
                if !ok {
                    err = fmt.Errorf("%v", r)
                }
                span := trace.SpanFromContext(c.Request.Context())
                span.RecordError(err, trace.WithStackTrace(true))
                span.SetStatus(codes.Error, err.Error())
                c.AbortWithStatus(http.StatusInternalServerError)
            }
        }()
        c.Next()
    }
}

router.Use(otelgin.Middleware(serviceName))
router.Use(otelRecovery())

抛出的 error 必须记录为 exception event，才能显示为 Issue。Auto-instrumentation 会处理 uncaught error；对于已捕获并自行处理的 error：

javascript

import { trace, SpanStatusCode } from "@opentelemetry/api";

const span = trace.getActiveSpan();
span?.recordException(error);
span?.setStatus({ code: SpanStatusCode.ERROR, message: error.message });

（Go：

span.RecordError(err, trace.WithStackTrace(true))

；stack trace 选项用于生成

exception.stacktrace

attribute。）

发生 exception 时必须返回 HTTP 500。 抛出异常或 panic 的 request 必须响应

，并将 span status 设置为

ERROR

。绝不能让它落入

2xx

。常见陷阱是 recover/panic middleware 虽然报告了 exception，却让 response writer 保留默认的

：这样 Traceway 会将 endpoint transaction 记录为成功，Endpoints 页面看起来健康，但 Issues 中充满错误，而且 exception 会成为无法关联的孤立项；在 distributed tracing 中，也无法关联到触发它的 frontend call。始终将“已记录 exception”与“返回

并将 span status 设置为

ERROR

”配套使用。真正的 client error 如果不是 bug（validation

、auth

、not-found

），应保留真实的 4xx status，并且一开始就不应将其记录为 exception。

Go 中存在同一陷阱的更明显版本。

otelgin

只会在

c.Next()

返回后记录 status，而 panic unwind 期间

c.Next()

不会返回，因此未被恢复的 panic 会导致 endpoint row 的 status 为 0，即使 Gin 自身的 recovery 已经向 client 返回 500，Issue 也会到达但没有 stack trace。请在

otelgin.Middleware

之后注册 recovery middleware，使其在 server span 内部运行：

// imports: fmt, net/http, go.opentelemetry.io/otel/codes, go.opentelemetry.io/otel/trace
func otelRecovery() gin.HandlerFunc {
    return func(c *gin.Context) {
        defer func() {
            if r := recover(); r != nil {
                err, ok := r.(error)
                if !ok {
                    err = fmt.Errorf("%v", r)
                }
                span := trace.SpanFromContext(c.Request.Context())
                span.RecordError(err, trace.WithStackTrace(true))
                span.SetStatus(codes.Error, err.Error())
                c.AbortWithStatus(http.StatusInternalServerError)
            }
        }()
        c.Next()
    }
}

router.Use(otelgin.Middleware(serviceName))
router.Use(otelRecovery())

Logs

Log

OTEL_LOGS_EXPORTER=otlp

wires the exporter only. The application's own log calls still need a bridge, or the Logs page stays empty while traces and metrics look perfectly healthy.

Node: add
```
@opentelemetry/winston-transport
```
, or the Pino or Bunyan instrumentation, so each record picks up
```
trace_id
```
and
```
span_id
```
.
Python, PHP, Java, .NET:
```
opentelemetry-instrument
```
and the language agents bridge the standard logger automatically.

Go: build an

sdklog.LoggerProvider

with

otlploghttp.WithEndpointURL(...)

, register it with

global.SetLoggerProvider(lp)

, and

defer lp.Shutdown(ctx)

or the last batch is lost on exit.

Emit from the request context (

c.Request.Context()

in Gin,

r.Context()

in net/http, the active context in Node). A line emitted from a background context carries no trace id and cannot be opened from the endpoint it belongs to. Traceway reads

severity_text

(or derives it from

severity_number

), the body,

service.name

, and the trace and span ids.

OTEL_LOGS_EXPORTER=otlp

只负责连接 exporter。Application 自身的 log 调用仍需要 bridge，否则即使 trace 和 metric 完全正常，Logs 页面也会为空。

Node：添加
```
@opentelemetry/winston-transport
```
，或使用 Pino/Bunyan instrumentation，使每条记录都带上
```
trace_id
```
和
```
span_id
```
。
Python、PHP、Java、.NET：
```
opentelemetry-instrument
```
和对应语言的 agent 会自动 bridge 标准 logger。

Go：构建带

otlploghttp.WithEndpointURL(...)

的

sdklog.LoggerProvider

，通过

global.SetLoggerProvider(lp)

defer lp.Shutdown(ctx)

，否则最后一批 log 会在退出时丢失。

从 request context 发出 log（Gin 中为

c.Request.Context()

，net/http 中为

r.Context()

，Node 中为 active context）。从 background context 发出的 log 不包含 trace id，无法从所属 endpoint 打开。Traceway 会读取

severity_text

（或从

severity_number

推导）、body、

service.name

，以及 trace 和 span id。

Go uses OpenTelemetry

Go 使用 OpenTelemetry

There is no separate Traceway Go SDK. It was retired, and Go instruments with

opentelemetry-go

exactly like every other backend:

go get go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

, then the same env vars as the block above. Host CPU and memory come from the Traceway OTel Agent (see "Deployment and Server Metrics"), not from the app.

不存在独立的 Traceway Go SDK。它已经退役，Go 与其他后端一样使用

opentelemetry-go

进行检测：

go get go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

，然后使用上述同一组 env var。Host CPU 和 memory 来自 Traceway OTel Agent（参见“部署与 Server Metrics”），而不是 app。

Step 5: Background Tasks (Boundaries and Labeling)

步骤 5：后台任务（边界与标记）

If "Analyze the Architecture" found background work, instrument it as Tasks. The rules:

Boundary: one Task = one execution of a unit of background work. A whole cron job run is one task. One queue message or job is one task. One CLI command invocation is one task. Per-item work inside a run (each email in a batch, each row in an import) is a child span of the task span, never a separate
```
CONSUMER
```
span.
Do not double-wrap. If a library's auto-instrumentation already emits
```
CONSUMER
```
spans (Kafka, RabbitMQ, Symfony Messenger consumers), wrapping them again creates duplicate Task entries.
Labeling: the span name IS the task name and the grouping key. Use a stable identifier like
```
cleanup-expired-sessions
```
or
```
process-email-queue
```
. Never embed job IDs, timestamps, or user IDs in the name; each unique name becomes a separate task group. Dynamic context (job ID, batch size) belongs in span attributes, where it shows on the task detail page without affecting grouping.
The kind must be
CONSUMER
. A root span with the default
```
SpanKind.INTERNAL
```
is dropped silently; this is the most common reason "my cron job doesn't show up". CLI commands may alternatively be root
```
INTERNAL
```
spans with a
```
console.command
```
attribute (Laravel/Symfony console instrumentation does this).

typescript

import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";

const tracer = trace.getTracer("my-app");

async function runScheduledJob() {
  await tracer.startActiveSpan(
    "cleanup-expired-sessions",
    { kind: SpanKind.CONSUMER },
    async (span) => {
      try {
        await doWork();
        span.setStatus({ code: SpanStatusCode.OK });
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        span.recordException(err);
        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
        throw error;
      } finally {
        span.end();
      }
    }
  );
}

(Go:

tracer.Start(ctx, "cleanup-expired-sessions", trace.WithSpanKind(trace.SpanKindConsumer))

如果“分析架构”发现了后台工作，将其检测为 Task。规则如下：

边界：一次 Task 对应一次后台工作单元的执行。 一次完整 cron job 运行是一个 task。一条 queue message 或 job 是一个 task。一次 CLI command 调用是一个 task。运行内部的逐项处理（批量中的每封 email、import 中的每一行）都是 task span 的 child span，绝不能成为独立的
```
CONSUMER
```
span。
不要重复包装。 如果 library 的 auto-instrumentation 已经发出
```
CONSUMER
```
span（Kafka、RabbitMQ、Symfony Messenger consumer），再次包装会创建重复的 Task 条目。
标记：span name 就是 task name，也是分组 key。 使用稳定标识符，例如
```
cleanup-expired-sessions
```
或
```
process-email-queue
```
。绝不要在 name 中嵌入 job ID、timestamp 或 user ID；每个唯一 name 都会形成独立的 task group。动态上下文（job ID、batch size）应放在 span attribute 中，这样可以在 task detail 页面查看，而不会影响分组。
Kind 必须为
CONSUMER
。使用默认
```
SpanKind.INTERNAL
```
的 root span 会被静默丢弃；这是“我的 cron job 没有显示”的最常见原因。CLI command 也可以使用带
```
console.command
```
attribute 的 root
```
INTERNAL
```
span（Laravel/Symfony console instrumentation 采用这种方式）。

typescript

import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";

const tracer = trace.getTracer("my-app");

async function runScheduledJob() {
  await tracer.startActiveSpan(
    "cleanup-expired-sessions",
    { kind: SpanKind.CONSUMER },
    async (span) => {
      try {
        await doWork();
        span.setStatus({ code: SpanStatusCode.OK });
      } catch (error) {
        const err = error instanceof Error ? error : new Error(String(error));
        span.recordException(err);
        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
        throw error;
      } finally {
        span.end();
      }
    }
  );
}

（Go：

tracer.Start(ctx, "cleanup-expired-sessions", trace.WithSpanKind(trace.SpanKindConsumer))

。）

Step 6: AI Traces

步骤 6：AI Trace

If "Analyze the Architecture" found AI/LLM dependencies, instrument the model calls. A span becomes an AI Trace when it carries at least one

gen_ai.*

attribute and matched none of the earlier classification rules. In practice that means: keep

gen_ai.*

off the HTTP route span (it becomes an Endpoint), keep it off

CONSUMER

spans (they become Tasks), and give the model call its own child span with

SpanKind.CLIENT

rather than

INTERNAL

, so a failed call that records

exception.*

attributes still produces its AI Trace. Since calls happen inside a request or task, that child span stays linked to its Endpoint or Task by trace ID.

Boundaries: one span per model call (one provider API request = one AI Trace row). A multi-step agent run is multiple spans sharing a stable

trace.name

(same labeling discipline as task names: no IDs or timestamps). For streaming, end the span when the stream finishes.

Conversational product? If "Analyze the Architecture" flagged a chatbot, assistant, or tool-calling agent, follow

ai-agent.md

in this skill directory instead of stopping at the table below. It covers

gen_ai.conversation.id

(multi-turn grouping), what value belongs in

user.id

(a stable end-customer id, never a session id), tool-call payload shapes, and sub-agents. Without those the Users tab stays empty, and the Conversations tab fills with one throwaway single-turn conversation per request, because Traceway falls back to the OTel trace id. That is worse than empty: it looks like the feature is working.

Attributes Traceway reads (all optional, set what is available):

Attribute	Meaning
`gen_ai.request.model` / `gen_ai.response.model`	Requested / serving model
`gen_ai.system` or `gen_ai.provider.name`	Provider ( `openai` , `anthropic` , ...)
`gen_ai.operation.name`	Operation ( `chat` , `embeddings` , ...)
`gen_ai.usage.input_tokens` / `.output_tokens` / `.total_tokens`	Token counts
`gen_ai.usage.input_tokens.cached` / `gen_ai.usage.output_tokens.reasoning`	Cached / reasoning tokens
`gen_ai.usage.input_cost` / `.output_cost` / `.total_cost`	Cost, when you compute pricing
`trace.name`	Agent/workflow grouping name
`gen_ai.conversation.id`	Multi-turn conversation grouping (falls back to `session.id` , then the OTel trace id)
`user.id`	End-user attribution: a stable customer id (account id, tenant id, or email), the same value across all of that user's conversations
`gen_ai.response.finish_reason`	Why generation stopped
`gen_ai.prompt` / `gen_ai.completion`	Conversation content, shown on the trace detail page (skip if content must not leave the app)

Conversation content is also read from

trace.input

trace.output

(or

span.input

span.output

) when

gen_ai.prompt

gen_ai.completion

are absent, and missing

total_tokens

total_cost

are computed from the input + output values. Token counts must be integer attributes and costs must be double or integer attributes. A number sent as a string is silently dropped and stored as 0, with no error on the export.

typescript

import { SpanKind } from "@opentelemetry/api";

return tracer.startActiveSpan("chat-completion", { kind: SpanKind.CLIENT }, async (span) => {
  const response = await openai.chat.completions.create({ model: "gpt-4o", messages });
  span.setAttributes({
    "gen_ai.system": "openai",
    "gen_ai.request.model": "gpt-4o",
    "gen_ai.usage.input_tokens": response.usage?.prompt_tokens ?? 0,
    "gen_ai.usage.output_tokens": response.usage?.completion_tokens ?? 0,
    "trace.name": "support-agent",
  });
  span.end();
  return response;
});

Zero-code path for OpenRouter users: in OpenRouter Settings -> Observability, add an OpenTelemetry Collector destination pointing at

https://<instance>/api/otel/v1/traces

with header

{"Authorization": "Bearer <project-token>"}

. Docs: https://docs.tracewayapp.com/client/openrouter

如果“分析架构”发现了 AI/LLM 依赖，则检测 model call。当 span 至少包含一个

gen_ai.*

attribute，且未匹配前述任何分类规则时，它会成为 AI Trace。实际操作意味着：不要在 HTTP route span 上设置

gen_ai.*

（它会成为 Endpoint），也不要在

CONSUMER

span 上设置（它们会成为 Task）；应给 model call 单独创建

SpanKind.CLIENT

child span，这样即使失败 call 记录了

exception.*

attribute，也仍会生成对应的 AI Trace。由于 call 发生在 request 或 task 内部，该 child span 会通过 trace ID 与 Endpoint 或 Task 保持关联。

边界：每次 model call 对应一个 span（一次 provider API request 对应一条 AI Trace row）。一次多步骤 Agent run 包含多个共享稳定

trace.name

的 span（命名规则与 task name 相同：不包含 ID 或 timestamp）。对于 streaming，在 stream 结束时结束 span。

对话式产品？ 如果“分析架构”标记了 chatbot、assistant 或 tool-calling Agent，请遵循此 skill 目录中的

ai-agent.md

，不要停留在下面的表格。它介绍了

gen_ai.conversation.id

（多轮分组）、

user.id

应使用的值（稳定的终端客户 ID，绝不能是 session id）、tool-call payload 结构以及 sub-agent。缺少这些信息时，Users tab 会保持为空，而 Conversations tab 会为每个 request 填充一个一次性的单轮 conversation，因为 Traceway 会回退到 OTel trace id。这比空白更糟：它看起来像功能已经正常运行。

Traceway 读取的 attribute（全部可选，设置可获得的值）：

Attribute	含义
`gen_ai.request.model` / `gen_ai.response.model`	请求的模型 / 实际提供服务的模型
`gen_ai.system` 或 `gen_ai.provider.name`	Provider（ `openai` 、 `anthropic` 等）
`gen_ai.operation.name`	Operation（ `chat` 、 `embeddings` 等）
`gen_ai.usage.input_tokens` / `.output_tokens` / `.total_tokens`	Token 数量
`gen_ai.usage.input_tokens.cached` / `.output_tokens.reasoning`	Cached token / reasoning token
`gen_ai.usage.input_cost` / `.output_cost` / `.total_cost`	计算价格时的费用
`trace.name`	Agent/workflow 分组名称
`gen_ai.conversation.id`	多轮 conversation 分组（回退到 `session.id` ，然后是 OTel trace id）
`user.id`	最终用户归因：稳定的客户 ID（account ID、tenant ID 或 email），该用户的所有 conversation 中都应使用相同值
`gen_ai.response.finish_reason`	生成停止的原因
`gen_ai.prompt` / `gen_ai.completion`	Conversation 内容，在 trace detail 页面中显示（如果内容不能离开 app，则跳过）

当缺少

gen_ai.prompt

gen_ai.completion

时，Conversation 内容也会从

trace.input

trace.output

（或

span.input

span.output

）读取；缺少

total_tokens

total_cost

时，会根据输入和输出值计算。Token 数量必须是 integer attribute，费用必须是 double 或 integer attribute。以 string 形式发送的数字会被静默丢弃并存储为 0，export 时不会报错。

typescript

import { SpanKind } from "@opentelemetry/api";

return tracer.startActiveSpan("chat-completion", { kind: SpanKind.CLIENT }, async (span) => {
  const response = await openai.chat.completions.create({ model: "gpt-4o", messages });
  span.setAttributes({
    "gen_ai.system": "openai",
    "gen_ai.request.model": "gpt-4o",
    "gen_ai.usage.input_tokens": response.usage?.prompt_tokens ?? 0,
    "gen_ai.usage.output_tokens": response.usage?.completion_tokens ?? 0,
    "trace.name": "support-agent",
  });
  span.end();
  return response;
});

OpenRouter 用户可使用零代码路径：在 OpenRouter Settings -> Observability 中，添加指向

https://<instance>/api/otel/v1/traces

的 OpenTelemetry Collector destination，并设置 header

{"Authorization": "Bearer <project-token>"}

。文档：https://docs.tracewayapp.com/client/openrouter

Step 7: Frontend and Mobile

步骤 7：前端与移动端

Frontend and mobile projects do NOT use OTel; they use the Traceway SDKs reporting to

/api/report

with connection string

<project-token>@https://<instance>/api/report

Browser (React / Vue / Svelte / jQuery / plain JS), three pieces, all expected:

SDK:
```
npm install @tracewayapp/react
```
(or
```
vue
```
,
```
svelte
```
,
```
jquery
```
,
```
frontend
```
for plain JS) and initialize with the connection string (React: wrap the app in
```
<TracewayProvider connectionString="...">
```
). Captures errors, web vitals, and session replay.

Bundler plugin:

npm install -D @tracewayapp/bundler-plugin

, then add

tracewayDebugIds()

from

@tracewayapp/bundler-plugin/vite

(or

/rollup

, or

TracewayDebugIdsWebpackPlugin

from

/webpack

) to the bundler config, with source maps enabled (

build.sourcemap: true

devtool: "source-map"

Source map upload:

npm install -D @tracewayapp/sourcemap-upload

, then run

traceway-sourcemaps --url <instance> --token <source-map-upload-token> --directory ./dist

as a postbuild or CI step (env vars:

TRACEWAY_URL

TRACEWAY_SOURCEMAP_TOKEN

). The upload token comes from the browser project and is a CI secret, never committed.

For the per-framework init code (plain JS, React, Vue, Svelte/SvelteKit, jQuery), the shared SDK options, error filtering, custom attributes, distributed tracing, and the full debug-ID + source map pipeline, read

frontend-js.md

in this skill directory. Online docs: https://docs.tracewayapp.com/client/react (or

vue

svelte

jquery

js-sdk

Full-stack JS (Next.js, SvelteKit, Remix): only when "Analyze the Architecture" confirmed the framework's server actually serves the app in production. A frontend-only deployment gets just the browser pieces above; a separate backend follows "Backend OTel Setup". When it is genuinely full-stack, integrate both sides under the two confirmed projects: server side follows "Backend OTel Setup" with the backend project's token, and browser side follows the three pieces above with the frontend project's token. For Next.js specifically, use the

instrumentation.ts

framework hook in the "Next.js server exception" above; never apply the generic Node preload to it.

For the Next.js browser build,

@tracewayapp/bundler-plugin

currently has a webpack entry point, not a Turbopack one. Set

productionBrowserSourceMaps: true

, add

TracewayDebugIdsWebpackPlugin

only when

!isServer && !dev

(the plugin is production-only and must not replace Next's development source-map mode), and make the production build run

next build --webpack

(Next.js 16 defaults to Turbopack, which otherwise ignores this plugin). After building, confirm client

.js

files contain

//# debugId=

and their

.js.map

siblings contain

debugId

, then upload

.next/static/chunks

with the React project's source-map upload token.

Mobile, always the platform SDK, never OTel:

Flutter:
```
flutter pub add traceway
```
, then
```
Traceway.run(connectionString: '<token>@https://<instance>/api/report', child: MyApp())
```
. Then check whether the release build is obfuscated (
```
--obfuscate --split-debug-info
```
): if it is, production crash stack traces arrive obfuscated and stay unreadable until the build's
```
.symbols
```
files are uploaded, so use the mobile project's upload token and wire up the symbol upload. For options, platform permissions, the navigator observer, screen recording, privacy masking, the obfuscation check and symbol upload, and the Flutter web caveat, read
```
flutter.md
```
in this skill directory. Docs: https://docs.tracewayapp.com/client/flutter
React Native:
```
npm install @tracewayapp/react-native
```
, wrap the app in
```
TracewayProvider
```
. Docs: https://docs.tracewayapp.com/client/react-native
Android (native Kotlin/Java): add
```
implementation("com.tracewayapp:traceway:1.0.1")
```
from Maven Central and call
```
Traceway.init(application = this, connectionString = "<token>@https://<instance>/api/report", options = TracewayOptions(version = "1.0.0"))
```
from
```
Application.onCreate()
```
(register the
```
Application
```
class in the manifest; no permission entry is needed, the AAR's own manifest declares
```
INTERNET
```
and
```
ACCESS_NETWORK_STATE
```
and the merger folds them in). It captures every uncaught Java/Kotlin exception on every thread plus manual
```
Traceway.captureException(...)
```
; errors and crashes only, no session replay. Release builds run R8, so production crashes arrive with renamed classes and rewritten line numbers and stay unreadable until the build's
```
mapping.txt
```
is uploaded: apply the
```
com.tracewayapp.symbols
```
Gradle plugin (
```
version "1.0.1"
```
, resolved from
```
mavenCentral()
```
), which injects
```
BuildConfig.TRACEWAY_PROGUARD_UUID
```
and uploads the mapping with the mobile project's upload token; pass that UUID into
```
TracewayOptions(proguardUuid = ...)
```
so each crash matches its mapping. For init code, options, the manifest, and the full Gradle plugin setup, read
```
android.md
```
in this skill directory. Docs: https://docs.tracewayapp.com/client/android
iOS / Swift (native SwiftUI or UIKit): add the Traceway iOS SDK via Swift Package Manager (
```
https://github.com/tracewayapp/traceway-ios.git
```
) and call
```
Traceway.start(connectionString: "<token>@https://<instance>/api/report", options: TracewayOptions(version: "1.0.0"))
```
as early as possible. It captures uncaught
```
NSException
```
s and fatal signals (hard crashes upload on the next launch) plus manual
```
Traceway.capture(...)
```
; it reports errors and crashes only (no session replay). Release crashes arrive as bare addresses until the build's dSYMs are uploaded, so set up dSYM upload with the mobile project's upload token. For init code, options, the debugger caveat, and dSYM upload, read
```
ios.md
```
in this skill directory. If the app is NOT a Swift app (Objective-C only, a cross-platform stack with no Traceway mobile SDK, or a team standardized on OpenTelemetry), there is no native SDK: use an OTel distribution like Honeycomb with its exporter pointed at
```
<instance>/api/otel
```
and a
```
Authorization: Bearer <project-token>
```
header, exactly like a backend (see "Backend OTel Setup"). The non-Swift path is also in
```
ios.md
```
.

Frontend 和 mobile project 不使用 OTel，而是使用 Traceway SDK 向

/api/report

上报，connection string 为

<project-token>@https://<instance>/api/report

。

Browser（React / Vue / Svelte / jQuery / plain JS）包含三个预期部分：

SDK：
```
npm install @tracewayapp/react
```
（或
```
vue
```
、
```
svelte
```
、
```
jquery
```
、
```
frontend
```
for plain JS），并使用 connection string 初始化（React：用
```
<TracewayProvider connectionString="...">
```
包裹 app）。用于捕获 error、web vitals 和 session replay。

Bundler plugin：

npm install -D @tracewayapp/bundler-plugin

，然后将

@tracewayapp/bundler-plugin/vite

中的

tracewayDebugIds()

（或

/rollup

，或

/webpack

中的

TracewayDebugIdsWebpackPlugin

）加入 bundler 配置，同时启用 source map（

build.sourcemap: true

devtool: "source-map"

）。

Source map 上传：

npm install -D @tracewayapp/sourcemap-upload

，然后运行

traceway-sourcemaps --url <instance> --token <source-map-upload-token> --directory ./dist

作为 postbuild 或 CI 步骤（env var：

TRACEWAY_URL

、

TRACEWAY_SOURCEMAP_TOKEN

）。Upload token 来自 browser project，是 CI secret，绝不能提交。

有关各 framework 的初始化代码（plain JS、React、Vue、Svelte/SvelteKit、jQuery）、共享 SDK option、error filter、自定义 attribute、distributed tracing，以及完整的 debug-ID + source map pipeline，请阅读此 skill 目录中的

frontend-js.md

。在线文档：https://docs.tracewayapp.com/client/react（或

vue

、

svelte

、

jquery

、

js-sdk

）。

Full-stack JS（Next.js、SvelteKit、Remix）：仅当“分析架构”确认 framework server 确实在生产环境提供 app 时才适用。仅 frontend 部署只使用上述 browser 部分；独立 backend 遵循“Backend OTel 设置”。如果确实是 full-stack，则在两个已确认项目下集成两端：server 端遵循“Backend OTel 设置”并使用 backend 项目 token，browser 端遵循上述三个部分并使用 frontend 项目 token。对于 Next.js server，使用上文“Next.js server 例外情况”中的

instrumentation.ts

framework hook；绝不将通用 Node preload 应用于它。

对于 Next.js browser build，

@tracewayapp/bundler-plugin

当前提供 webpack entry point，但不提供 Turbopack entry point。设置

productionBrowserSourceMaps: true

，仅在

!isServer && !dev

时添加

TracewayDebugIdsWebpackPlugin

（该 plugin 仅用于 production，且不能替换 Next 的 development source-map mode），并让 production build 运行

next build --webpack

（Next.js 16 默认使用 Turbopack，否则会忽略该 plugin）。构建后，确认 client

.js

文件包含

//# debugId=

，且对应的

.js.map

文件包含

debugId

，然后使用 React 项目的 source-map upload token 上传

.next/static/chunks

。

Mobile 始终使用 platform SDK，绝不使用 OTel：

Flutter：
```
flutter pub add traceway
```
，然后执行
```
Traceway.run(connectionString: '<token>@https://<instance>/api/report', child: MyApp())
```
。接着检查 release build 是否启用混淆（
```
--obfuscate --split-debug-info
```
）：如果启用，生产环境 crash stack trace 会以混淆形式到达，在上传构建生成的
```
.symbols
```
文件之前无法阅读。因此应使用 mobile 项目的 upload token 并配置 symbol upload。有关 option、platform permission、navigator observer、screen recording、privacy mask、混淆检查和 symbol upload，以及 Flutter web 注意事项，请阅读此 skill 目录中的
```
flutter.md
```
。文档：https://docs.tracewayapp.com/client/flutter
React Native：
```
npm install @tracewayapp/react-native
```
，使用
```
TracewayProvider
```
包裹 app。文档：https://docs.tracewayapp.com/client/react-native
Android（原生 Kotlin/Java）：从 Maven Central 添加
```
implementation("com.tracewayapp:traceway:1.0.1")
```
，并在
```
Application.onCreate()
```
中调用
```
Traceway.init(application = this, connectionString = "<token>@https://<instance>/api/report", options = TracewayOptions(version = "1.0.0"))
```
（在 manifest 中注册
```
Application
```
class；无需 permission entry，因为 AAR 自身的 manifest 会声明
```
INTERNET
```
和
```
ACCESS_NETWORK_STATE
```
，manifest merger 会将它们合并进来）。它会捕获每个 thread 上所有未捕获的 Java/Kotlin exception，以及手动调用
```
Traceway.captureException(...)
```
的错误；仅捕获 error 和 crash，不提供 session replay。Release build 会运行 R8，因此生产环境 crash 到达时 class 名已被重写、行号也已转换，在上传构建生成的
```
mapping.txt
```
前无法阅读：应用
```
com.tracewayapp.symbols
```
Gradle plugin（
```
version "1.0.1"
```
，从
```
mavenCentral()
```
解析），它会注入
```
BuildConfig.TRACEWAY_PROGUARD_UUID
```
并使用 mobile 项目的 upload token 上传 mapping；将该 UUID 传入
```
TracewayOptions(proguardUuid = ...)
```
，使每个 crash 都能匹配对应 mapping。有关初始化代码、option、manifest 和完整的 Gradle plugin 设置，请阅读此 skill 目录中的
```
android.md
```
。文档：https://docs.tracewayapp.com/client/android
iOS / Swift（原生 SwiftUI 或 UIKit）：通过 Swift Package Manager 添加 Traceway iOS SDK（
```
https://github.com/tracewayapp/traceway-ios.git
```
），并尽早调用
```
Traceway.start(connectionString: "<token>@https://<instance>/api/report", options: TracewayOptions(version: "1.0.0"))
```
。它会捕获未捕获的
```
NSException
```
和 fatal signal（hard crash 会在下次启动时上传），以及手动调用
```
Traceway.capture(...)
```
的错误；仅报告 error 和 crash（无 session replay）。Release crash 最初只显示裸地址，直到上传构建生成的 dSYM，因此应使用 mobile 项目的 upload token 配置 dSYM 上传。有关初始化代码、option、debugger 注意事项和 dSYM 上传，请阅读此 skill 目录中的
```
ios.md
```
。如果 app 不是 Swift app（仅使用 Objective-C、没有 Traceway mobile SDK 的跨平台技术栈，或团队统一采用 OpenTelemetry），则不存在原生 SDK：使用 Honeycomb 等 OTel distribution，将 exporter 指向
```
<instance>/api/otel
```
，并设置
```
Authorization: Bearer <project-token>
```
header，与 backend 完全相同（参见“Backend OTel 设置”）。非 Swift 路径也记录在
```
ios.md
```
中。

Step 8: Deployment and Server Metrics

步骤 8：部署与 Server Metrics

Use the deployment and host-metrics choice confirmed in "Propose and Confirm the Project Map". If it remains unresolved, ask before changing deployment configuration:

How is this project deployed? Docker on a VM / directly on a VM or bare metal / Kubernetes / serverless or PaaS.
Do you want server (host) metrics tracked in Traceway? CPU, memory, disk, filesystem, network of the machine running the app.

Deployment	Wants host metrics	What to do
Docker on a VM, or directly on a VM/host	Yes	Install the Traceway OTel Agent on the host (below). For Docker deploys this is the default; the agent goes on the host, not in a container.
Kubernetes	Any	Not the agent, which is a host service. Deploy the two collector workloads in `kubernetes.md` in this skill directory: a DaemonSet for node metrics, pod metrics and container logs, and a one-replica Deployment for cluster state and events. In-process app metrics still flow via the OTLP metrics exporter from "Backend OTel Setup".
Serverless / PaaS	Any	No host to install on; skip.
Anything	No	Skip.

On Kubernetes, stop here and read

kubernetes.md

in this skill directory. The four things that decide whether it works (

service.name

per node, the three

*.utilization

metrics that ship disabled,

k8s.cluster.name

, and

root_path: /hostfs

) are all easy to miss, and getting any of them wrong produces a plausible-looking config that reports nothing useful.

The agent is a tiny pre-configured OTel Collector that scrapes host metrics every 60s. It MUST use the same backend project token as the API, workers, tasks, and AI traces. Install it on the host (Linux systemd / macOS launchd; PowerShell installer exists for Windows):

bash

curl -fsSL https://install.tracewayapp.com/install.sh | \
  TRACEWAY_TOKEN=<project-token> \
  TRACEWAY_ENDPOINT=https://<instance>/api/otel \
  TRACEWAY_SERVICE_NAME=<host-label, e.g. api-prod-eu-1> \
  bash

```
TRACEWAY_ENDPOINT
```
ends in
```
/api/otel
```
and is required for self-hosted instances; omit only for Traceway Cloud.
Optional:
```
TRACEWAY_LOG_PATHS
```
(comma-separated globs to tail as logs),
```
TRACEWAY_PROCESS_NAMES
```
(per-process metrics).
Re-running the installer upgrades in place, so the command is safe to keep in provisioning scripts.
If the repo has host provisioning or deploy scripts (cloud-init, Ansible, Terraform
```
user_data
```
,
```
deploy.sh
```
), add the command there with the token referenced from a secret. Otherwise hand the operator the filled-in one-liner; do not modify the repo.

Metrics arrive within ~60s under their hostmetrics names (

system.cpu.utilization

system.memory.usage

, ...). The host is identified by the

server_name

tag, which comes from

TRACEWAY_SERVICE_NAME

; resource metadata such as

host.name

host.id

host.arch

os.type

, and cloud region is also retained, but it does not replace that canonical identity. Give every host a distinct

TRACEWAY_SERVICE_NAME

or the hosts cannot be told apart. The organization overview recognizes these hostmetrics directly, but the legacy Go SDK CPU/memory widgets still read their exact SDK metric names. Install the OTelemetry Server Agent dashboard template for the full set: open the command palette with Cmd K, search for it, and it installs a dashboard already wired to

system.cpu.utilization

system.memory.*

system.filesystem.*

system.disk.*

and

system.network.*

. Custom widgets cover anything the template misses. Agent repo: https://github.com/tracewayapp/traceway-otel-agent

使用“提出并确认项目映射”中确认的部署和 host-metrics 选择。如果仍未解决，应在修改部署配置前询问：

该项目如何部署？ VM 上的 Docker / 直接运行在 VM 或 bare metal 上 / Kubernetes / serverless 或 PaaS。
是否要在 Traceway 中跟踪 server（host）metrics？ 即运行 app 的机器的 CPU、memory、disk、filesystem 和 network。

部署方式	需要 host metrics	操作
VM 上的 Docker，或直接运行在 VM/host 上	是	在 host 上安装 Traceway OTel Agent（见下文）。对于 Docker 部署，这是默认方案；Agent 安装在 host 上，而不是 container 中。
Kubernetes	任意	不使用作为 host service 的 Agent。按照此 skill 目录中的 `kubernetes.md` 部署两个 collector workload：用于 node metric、pod metric 和 container log 的 DaemonSet，以及用于 cluster state 和 event 的单副本 Deployment。In-process app metric 仍通过“Backend OTel 设置”中的 OTLP metrics exporter 传输。
Serverless / PaaS	任意	没有可安装 Agent 的 host；跳过。
任意	否	跳过。

在 Kubernetes 上，到此停止并阅读此 skill 目录中的

kubernetes.md

。决定其是否工作的四项关键配置（每个 node 的

service.name

、默认禁用的三个

*.utilization

metric、

k8s.cluster.name

和

root_path: /hostfs

）都很容易遗漏，任何一项配置错误都会产生看似合理但实际上没有 useful data 的配置。

Agent 是一个预配置的小型 OTel Collector，每 60 秒抓取一次 host metric。它必须使用与 API、worker、task 和 AI trace 相同的 backend 项目 token。在 host 上安装它（Linux systemd / macOS launchd；Windows 提供 PowerShell installer）：

bash

curl -fsSL https://install.tracewayapp.com/install.sh | \\
  TRACEWAY_TOKEN=<project-token> \\
  TRACEWAY_ENDPOINT=https://<instance>/api/otel \\
  TRACEWAY_SERVICE_NAME=<host-label, e.g. api-prod-eu-1> \\
  bash

```
TRACEWAY_ENDPOINT
```
必须以
```
/api/otel
```
结尾，self-hosted instance 必须设置；对于 Traceway Cloud 则省略。
可选：
```
TRACEWAY_LOG_PATHS
```
（要采集日志的逗号分隔 glob）、
```
TRACEWAY_PROCESS_NAMES
```
（per-process metric）。
重新运行 installer 会原地升级，因此该命令可安全保留在 provisioning script 中。
如果仓库中有 host provisioning 或 deploy script（cloud-init、Ansible、Terraform
```
user_data
```
、
```
deploy.sh
```
），应将命令加入其中，并通过 secret 引用 token。否则向 operator 提供填好值的一行命令；不要修改仓库。

Metric 约 60 秒后以 hostmetric name 到达（

system.cpu.utilization

、

system.memory.usage

等）。Host 通过

server_name

tag 标识，该 tag 来自

TRACEWAY_SERVICE_NAME

；

host.name

、

host.id

、

host.arch

、

os.type

和 cloud region 等 resource metadata 也会保留，但不能替代这一 canonical identity。为每个 host 设置不同的

TRACEWAY_SERVICE_NAME

，否则无法区分不同 host。Organization overview 可以直接识别这些 hostmetric，但旧版 Go SDK 的 CPU/memory widget 仍读取其精确 SDK metric name。安装 OTelemetry Server Agent dashboard template 可获得完整集合：打开命令面板（Cmd K），搜索该模板，即可安装已经连接到

system.cpu.utilization

、

system.memory.*

、

system.filesystem.*

、

system.disk.*

和

system.network.*

的 dashboard。自定义 widget 可覆盖模板未覆盖的内容。Agent repo：https://github.com/tracewayapp/traceway-otel-agent

Step 9: Verify

步骤 9：验证

Every dashboard page named below is at

<instance>/<page>

/endpoints

/issues

/tasks

/ai-traces

/logs

/dashboards

. Set the time picker to the last 15 minutes before reading any of them. Verify each project independently and finish with a project-to-component summary.

When the CLI applied the plan, the local env files hold real values, so run local verification now rather than deferring it. Deployment environments are verified only after the user completes the website's Next Steps panel; re-state which variables must exist there before that verification can pass.

Backend project
- Run
```
curl <app>/api/users/1
```
  , then
```
/2
```
  , then
```
/3
```
  , and open
```
/endpoints
```
  . Exactly one row,
```
GET /api/users/:id
```
  , with non-zero status codes. Three rows means
```
http.route
```
  is not being set. Fix that before checking anything else.
- Two results that look broken but are not: a request to a URL matching no route arrives as
```
UNMATCHED
```
  , not as the URL you typed; and if the project has "drop healthy healthchecks" enabled, successful
```
/health
```
  requests are discarded on ingest, so never use a healthcheck route as the smoke test.
- Trigger a handled or test exception, then open
```
/issues
```
  . The exception is listed with its endpoint or task context, and that request's endpoint row shows status 500.
- Open one endpoint row: database queries and outgoing HTTP calls appear as child spans.
- Run each background job once, then open
```
/tasks
```
  . One row per job, under a stable name with no ids or timestamps in it.
- If logs were wired, emit one INFO and one ERROR line inside a request, then open
```
/logs
```
  . Both carry the same trace id as that endpoint.
- If "AI Traces" applied, make one model call, then open
```
/ai-traces
```
  . The call is listed with model, tokens, and cost where available.
- Open
```
/dashboards
```
  and confirm application/runtime metrics arrive. If the OTel Agent was installed, host metrics reach this same backend project within about 60 seconds, each host under its own
```
server_name
```
  tag.
- If host or Kubernetes metrics were set up, open
```
/organization
```
  . Every host and node appears as its own instance row with CPU, memory and disk. Kubernetes nodes are grouped by cluster. One row where you expected several means
```
service.name
```
  is not distinct per machine; empty rings mean the
```
*.utilization
```
  metrics are not enabled.
Browser project
- Trigger a test browser error and confirm it appears in this project, not the backend project.
- Confirm the stack resolves to original source files and lines after the matching source maps and bundles are uploaded.
- If distributed tracing was configured, confirm a browser issue or request links to its backend trace.
Each mobile project
- Trigger the platform's safe test error or crash flow and confirm it appears only in the matching mobile project.
- For obfuscated Flutter, minified Android, or Release iOS builds, confirm the matching symbols, R8 mapping, or dSYM resolves the production stack.
Credential and topology audit
- Confirm browser and mobile integrations do not use the backend token, and that the OTLP exporter does not use a browser project's token (rule 3 in Step 4).
- Confirm APIs, workers, schedulers, AI calls, and host metrics use the backend project unless the user approved an isolation boundary.
- Report any verification that could not run because a local, deployment, or CI variable is not yet populated.

If the

traceway

CLI is installed, run

traceway login

, select the backend project with

traceway projects use <project-id>

(or pass

--project <project-id>

on every call), then:

bash

traceway endpoints list --since 15m
traceway exceptions list --since 15m
traceway logs query --since 15m
traceway metrics query --name system.cpu.utilization --since 15m

Tasks and AI traces have no

list

subcommand, only

show <id>

, so check those two on

/tasks

and

/ai-traces

in the dashboard.

Hand the user a test drive. After your own verification, finish by telling the user exactly how to see the connection working themselves: two or three copy-paste actions against THEIR app, each paired with the Traceway page it lands on. For example: hit one real parametrized endpoint a few times (
```
curl <their-app>/api/users/1
```
,
```
/2
```
,
```
/3
```
becomes a single row on
```
/endpoints
```
within seconds), trigger their app's error path or a deliberate test exception (appears on
```
/issues
```
linked to the failing request), and run or wait for one background job (
```
/tasks
```
). Use their actual routes and commands, remind them to set the dashboard time picker to the last 15 minutes, and note that approval already dropped them on the right project's dashboard.

以下所有 dashboard 页面均位于

<instance>/<page>

：

/endpoints

、

/issues

、

/tasks

、

/ai-traces

、

/logs

、

/dashboards

。读取任何页面前，将时间选择器设为最近 15 分钟。分别验证每个项目，最后给出项目与组件的对应摘要。

当 CLI apply 计划后，本地 env 文件中已包含真实值，因此应立即进行本地验证，不要推迟。Deployment environment 只有在用户完成 website 的 Next Steps panel 后才能验证；在此之前，应再次说明必须存在哪些变量。

Backend project
- 运行
```
curl <app>/api/users/1
```
  ，然后运行
```
/2
```
  和
```
/3
```
  ，再打开
```
/endpoints
```
  。应该恰好出现一行
```
GET /api/users/:id
```
  ，且 status code 非零。如果出现三行，说明没有设置
```
http.route
```
  。继续检查其他内容之前先修复它。
- 有两种看起来异常但实际正常的情况：未匹配任何 route 的 request 会显示为
```
UNMATCHED
```
  ，而不是输入的 URL；如果项目启用了“drop healthy healthchecks”，成功的
```
/health
```
  request 会在 ingest 时被丢弃，因此绝不能使用 healthcheck route 进行 smoke test。
- 触发一个已处理或测试 exception，然后打开
```
/issues
```
  。Exception 应列出，并带有对应 endpoint 或 task context，同时该 request 的 endpoint row 显示 status 500。
- 打开一个 endpoint row：database query 和 outgoing HTTP call 应显示为 child span。
- 每个 background job 运行一次，然后打开
```
/tasks
```
  。每个 job 应对应一行，并使用不含 ID 或 timestamp 的稳定 name。
- 如果已连接 log，在 request 内发出一个 INFO 和一个 ERROR log，然后打开
```
/logs
```
  。两者应携带与该 endpoint 相同的 trace id。
- 如果应用了“AI Traces”，发起一次 model call，然后打开
```
/ai-traces
```
  。应列出该 call，并尽可能显示 model、token 和 cost。
- 打开
```
/dashboards
```
  ，确认 application/runtime metric 已到达。如果安装了 OTel Agent，host metric 会在约 60 秒后到达同一个 backend 项目，每个 host 使用各自的
```
server_name
```
  tag。
- 如果配置了 host 或 Kubernetes metric，打开
```
/organization
```
  。每个 host 和 node 应显示为独立 instance row，并包含 CPU、memory 和 disk。Kubernetes node 按 cluster 分组。如果预期有多个实例却只有一行，说明
```
service.name
```
  没有针对每台机器进行区分；如果 ring 为空，则说明
```
*.utilization
```
  metric 未启用。
Browser project
- 触发一个测试 browser error，并确认它出现在该项目中，而不是 backend 项目中。
- 确认上传匹配的 source map 和 bundle 后，stack 能解析到原始 source file 和 line。
- 如果配置了 distributed tracing，确认 browser issue 或 request 能链接到对应的 backend trace。
每个 mobile project
- 触发对应 platform 的安全测试 error 或 crash flow，并确认它只出现在匹配的 mobile 项目中。
- 对于启用混淆的 Flutter、经过 minification 的 Android 或 Release iOS build，确认匹配的 symbol、R8 mapping 或 dSYM 能解析生产环境 stack。
凭据与拓扑审计
- 确认 browser 和 mobile integration 没有使用 backend token，且 OTLP exporter 没有使用 browser 项目的 token（步骤 4 中的规则 3）。
- 确认 API、worker、scheduler、AI call 和 host metric 使用 backend 项目，除非用户批准了隔离边界。
- 报告任何因本地、deployment 或 CI 变量尚未填充而无法执行的验证。

如果已安装

traceway

CLI，运行

traceway login

，使用

traceway projects use <project-id>

选择 backend 项目（或在每次调用时传入

--project <project-id>

），然后执行：

bash

traceway endpoints list --since 15m
traceway exceptions list --since 15m
traceway logs query --since 15m
traceway metrics query --name system.cpu.utilization --since 15m

Task 和 AI trace 没有

list

子命令，只有

show <id>

，因此应在 dashboard 的

/tasks

和

/ai-traces

页面检查这两项。

让用户亲自试用。 完成自行验证后，最后准确告诉用户如何亲自查看连接是否正常工作：提供两到三个可复制粘贴、针对他们的 app 执行的操作，并分别指出结果对应的 Traceway 页面。例如，对一个真实参数化 endpoint 调用几次（
```
curl <their-app>/api/users/1
```
、
```
/2
```
、
```
/3
```
会在数秒内合并为
```
/endpoints
```
中的一行）、触发 app 的 error path 或 deliberate test exception（出现在
```
/issues
```
并链接到失败的 request），运行或等待一个 background job（
```
/tasks
```
）。使用他们的真实 route 和命令，提醒他们将 dashboard 时间选择器设为最近 15 分钟，并说明批准操作已将他们带到正确项目的 dashboard。