# OpenTelemetry 可观测性

Deno 内置 OpenTelemetry 集成，可以通过 OTLP 导出运行时指标、HTTP traces、`console` 日志和应用自定义 telemetry。

## 最短验证

```bash
OTEL_DENO=true \
OTEL_EXPORTER_OTLP_PROTOCOL=console \
deno run --allow-net main.ts
```

`console` exporter 适合确认信号是否产生；生产通常把 OTLP 发送到 Collector：

```bash
OTEL_DENO=true \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_SERVICE_NAME=orders-api \
deno run --allow-net=0.0.0.0:8000,otel-collector:4318 main.ts
```

运行时读取 OTEL 配置与应用调用 `Deno.env.get()` 是不同路径；后者仍受 `--allow-env` 控制。无论哪种方式，都把 telemetry endpoint、headers 和 service name 纳入明确配置契约，不在日志中输出 header 值。

## 自定义 spans

```ts
import { trace } from "npm:@opentelemetry/api";

const tracer = trace.getTracer("orders");
await tracer.startActiveSpan("create-order", async (span) => {
  try {
    span.setAttribute("order.channel", "web");
    // business operation
  } catch (error) {
    span.recordException(error as Error);
    throw error;
  } finally {
    span.end();
  }
});
```

## 生产边界

- 不把 token、Cookie、Authorization 或完整 prompt 写入 span attributes。
- 为请求、数据库和工具调用传递 trace context。
- 采样率、导出超时和队列大小必须有上限。
- 监控 exporter 自身失败，不能让 telemetry 阻塞核心请求。
- 本地、CI、预览和生产使用不同 service/environment 属性。

官方依据：[OpenTelemetry](https://docs.deno.com/runtime/fundamentals/open_telemetry/)。