DSN 配置说明

DSN（Data Source Name）是连接 APM 平台的凭证字符串，包含了认证和连接所需的所有信息。本文将详细介绍如何获取、配置和使用 DSN。

什么是 DSN？

DSN 是一个包含连接信息的字符串，类似于数据库连接串。它包含：

协议类型: http 或 https
认证信息: 项目 ID 和密钥
服务地址: APM 平台的 endpoint
可选参数: 如项目名称、环境等

DSN 格式

https://<token>@<endpoint>/<project_id>?grpc=<port>

示例:

https://abc123def456@api.uptrace.dev/1234
https://token@apm-platform.com:443/project1?grpc=4317

内部平台示例:

https://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317

获取 DSN

方法 1: 从 APM 平台控制台获取

登录 APM 平台控制台
- 内部平台：https://uptrace.inner.youdao.com/
选择项目
进入项目设置页面
在"连接详情"或"Connection Details"部分找到 DSN
点击"显示 DSN"按钮
复制 DSN 字符串

详细步骤请参考：DSN 配置与查看

方法 2: 联系平台管理员

如果您无法访问控制台，请联系您的平台管理员获取 DSN。

方法 3: 使用 API 生成

某些平台支持通过 API 生成 DSN：

curl -X POST https://your-apm-platform.com/api/v1/projects/1234/dsn \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-service",
    "environment": "production"
  }'

DSN 的组成部分

1. Token（令牌）

用于认证的密钥，通常是一个随机字符串：

abc123def456

安全建议:

不要在代码中硬编码 DSN
不要提交 DSN 到版本控制系统
使用环境变量或密钥管理服务
定期轮换 Token

2. Endpoint（服务地址）

APM 平台的服务地址：

内部平台：

uptrace-grpc.yodao.cn    # HTTP 端点
uptrace-grpc.yodao.cn:4317  # gRPC 端点（推荐）

其他平台示例：

api.uptrace.dev
apm-platform.com
tellus.corp.youdao.com

3. Project ID（项目 ID）

标识您的项目：

1234
project-prod
my-service

4. 可选参数

grpc 端口:

?grpc=4317

指定 gRPC 协议的端口（OTLP over gRPC）。

多个参数:

?grpc=4317&env=production&region=us-east-1

配置 DSN

方法 1: 使用环境变量（推荐）

最安全和灵活的方式是使用环境变量：

# 直接设置 DSN（内部平台示例）
export UPTRACE_DSN="https://abc123@uptrace-grpc.yodao.cn/1234?grpc=4317"

# 或者通过 OTLP Headers 传递（推荐）
export OTEL_EXPORTER_OTLP_ENDPOINT="uptrace-grpc.yodao.cn:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=https://abc123@uptrace-grpc.yodao.cn/1234?grpc=4317"

# 使用 HTTP 端点（如果 gRPC 端口被限制）
export OTEL_EXPORTER_OTLP_ENDPOINT="https://uptrace-grpc.yodao.cn"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=https://abc123@uptrace-grpc.yodao.cn/1234?grpc=4317"

方法 2: 配置文件

创建配置文件（如 .env）:

# .env
UPTRACE_DSN=https://abc123@api.uptrace.dev/1234?grpc=4317
OTEL_SERVICE_NAME=my-service
OTEL_SERVICE_VERSION=1.0.0

加载配置:

# 使用 dotenv
source .env

# 或在应用启动时加载
export $(cat .env | xargs)

方法 3: 密钥管理服务

对于生产环境，建议使用密钥管理服务：

AWS Secrets Manager:

export UPTRACE_DSN=$(aws secretsmanager get-secret-value \
  --secret-id prod/apm/dsn \
  --query SecretString \
  --output text)

HashiCorp Vault:

export UPTRACE_DSN=$(vault kv get -field=dsn secret/apm/production)

Kubernetes Secret:

apiVersion: v1
kind: Secret
metadata:
  name: apm-credentials
type: Opaque
stringData:
  dsn: "https://abc123@api.uptrace.dev/1234?grpc=4317"
---
apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
  - name: app
    image: my-app:latest
    env:
    - name: UPTRACE_DSN
      valueFrom:
        secretKeyRef:
          name: apm-credentials
          key: dsn

在不同语言中使用 DSN

Go

import (
    "os"
    "github.com/uptrace/uptrace-go/uptrace"
)

func main() {
    // 从环境变量读取
    dsn := os.Getenv("UPTRACE_DSN")
    
    uptrace.ConfigureOpentelemetry(
        uptrace.WithDSN(dsn),
        uptrace.WithServiceName("my-service"),
    )
    defer uptrace.Shutdown(context.Background())
    
    // ... 应用代码
}

Python

import os
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# 解析 DSN
dsn = os.environ.get("UPTRACE_DSN")

# 或使用 uptrace 库
# import uptrace
# uptrace.configure_opentelemetry(dsn=dsn)

# 手动配置 OTLP Exporter
exporter = OTLPSpanExporter(
    endpoint="api.uptrace.dev:4317",
    headers=(("uptrace-dsn", dsn),)
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

Java

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;

public class Application {
    public static void main(String[] args) {
        String dsn = System.getenv("UPTRACE_DSN");
        
        OtlpGrpcSpanExporter spanExporter = OtlpGrpcSpanExporter.builder()
            .setEndpoint("uptrace-grpc.yodao.cn:4317")
            .addHeader("uptrace-dsn", dsn)
            .build();

        SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
            .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
            .build();

        OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
            .setTracerProvider(tracerProvider)
            .build();
    }
}

JavaScript / Node.js

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');

const dsn = process.env.UPTRACE_DSN;

const exporter = new OTLPTraceExporter({
  url: 'uptrace-grpc.yodao.cn:4317',
  headers: {
    'uptrace-dsn': dsn,
  },
});

const provider = new NodeTracerProvider();
provider.addSpanProcessor(new BatchSpanProcessor(exporter));
provider.register();

.NET

using System;
using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Exporter;

var dsn = Environment.GetEnvironmentVariable("UPTRACE_DSN");

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri("uptrace-grpc.yodao.cn:4317");
        options.Headers = $"uptrace-dsn={dsn}";
    })
    .Build();

环境特定配置

开发环境

# .env.development
UPTRACE_DSN=https://dev-token@dev.apm-platform.com/dev-project
OTEL_SERVICE_NAME=my-service-dev
OTEL_TRACES_SAMPLER_ARG=1.0  # 100% 采样
OTEL_LOG_LEVEL=debug

测试环境

# .env.test
UPTRACE_DSN=https://test-token@test.apm-platform.com/test-project
OTEL_SERVICE_NAME=my-service-test
OTEL_TRACES_SAMPLER_ARG=0.5  # 50% 采样
OTEL_LOG_LEVEL=info

生产环境

# .env.production
UPTRACE_DSN=https://prod-token@api.apm-platform.com/prod-project
OTEL_SERVICE_NAME=my-service
OTEL_TRACES_SAMPLER_ARG=0.1  # 10% 采样
OTEL_LOG_LEVEL=warn

DSN 验证

验证 DSN 格式

使用以下脚本验证 DSN 格式：

#!/bin/bash
DSN="$1"

if [[ $DSN =~ ^https?://[^@]+@[^/]+/[^?]+ ]]; then
    echo "✓ DSN format is valid"
    
    # 提取组件
    PROTOCOL=$(echo "$DSN" | grep -oP '^https?')
    TOKEN=$(echo "$DSN" | grep -oP '://\K[^@]+')
    ENDPOINT=$(echo "$DSN" | grep -oP '@\K[^/]+')
    PROJECT=$(echo "$DSN" | grep -oP '/\K[^?]+')
    
    echo "Protocol: $PROTOCOL"
    echo "Token: ${TOKEN:0:8}..."
    echo "Endpoint: $ENDPOINT"
    echo "Project: $PROJECT"
else
    echo "✗ Invalid DSN format"
    exit 1
fi

使用:

./validate-dsn.sh "https://abc123@api.uptrace.dev/1234"

测试连接

发送测试数据验证 DSN：

# 使用 curl 测试
curl -X POST https://api.uptrace.dev:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "uptrace-dsn: https://abc123@api.uptrace.dev/1234" \
  -d '{
    "resourceSpans": [{
      "resource": {
        "attributes": [{
          "key": "service.name",
          "value": {"stringValue": "test-service"}
        }]
      },
      "scopeSpans": []
    }]
  }'

常见问题

1. DSN 无效或已过期

错误信息:

authentication failed: invalid DSN

解决方案:

检查 DSN 格式是否正确
确认 Token 是否有效
联系管理员重新生成 DSN
检查 DSN 是否已被撤销

2. 网络连接问题

错误信息:

failed to connect to endpoint: connection refused

解决方案:

检查 endpoint 地址是否正确
确认网络连接是否正常
检查防火墙规则
验证端口是否正确（gRPC: 4317, HTTP: 4318）

3. 权限不足

错误信息:

permission denied: insufficient privileges

解决方案:

确认 DSN 对应的项目权限
检查是否有写入权限
联系管理员分配正确的权限

4. 项目不存在

错误信息:

project not found

解决方案:

确认 Project ID 是否正确
检查项目是否已被删除
联系管理员确认项目状态

安全最佳实践

1. 不要硬编码 DSN

❌ 错误做法:

// 不要这样做！
dsn := "https://abc123@api.uptrace.dev/1234"

✅ 正确做法:

dsn := os.Getenv("UPTRACE_DSN")
if dsn == "" {
    log.Fatal("UPTRACE_DSN environment variable is required")
}

2. 不要提交 DSN 到版本控制

在 .gitignore 中添加：

.env
.env.*
*.local
secrets/

3. 使用不同的 DSN for 不同环境

开发环境使用开发 DSN
测试环境使用测试 DSN
生产环境使用生产 DSN
每个环境的 DSN 权限隔离

4. 定期轮换 Token

建议每 90 天轮换一次 Token：

生成新的 DSN
更新环境变量
验证新 DSN 工作正常
撤销旧的 DSN

5. 限制 DSN 的访问范围

仅授予必要的权限
使用只读 DSN 用于查询
使用写入 DSN 用于数据采集

6. 监控 DSN 使用情况

记录 DSN 的使用日志
监控异常的访问模式
设置告警规则

DSN 与 OTLP 配置的关系

使用 DSN（uptrace 专用）

export UPTRACE_DSN="https://abc123@api.uptrace.dev/1234?grpc=4317"

等价于：

使用标准 OTLP 配置

export OTEL_EXPORTER_OTLP_ENDPOINT="uptrace-grpc.yodao.cn:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=https://abc123@api.uptrace.dev/1234"

推荐做法:

如果使用 uptrace SDK，使用 UPTRACE_DSN。

如果使用纯 OpenTelemetry SDK，使用标准 OTLP 配置。

下一步

现在您已经了解了 DSN 的配置方法，接下来：

环境变量配置 - 了解所有配置选项
选择您的语言开始接入：

参考资源

在Gitlab上编辑本文档