Skip to content
OpenTelemetry 接入文档

DSN 配置与查看

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

什么是 DSN？

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

  • 协议类型: http 或 https
  • 认证信息: 项目 Token
  • 服务地址: Uptrace 平台的 endpoint
  • 项目标识: 项目 ID
  • 可选参数: 如 gRPC 端口等

DSN 格式

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

内部平台示例:

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

如何查看 DSN

方法 1: 从平台控制台查看（推荐）

  1. 登录平台

  2. 选择项目

    • 在项目列表中选择要查看的项目
    • 点击项目名称进入项目详情页

  3. 进入项目设置

    • 点击右上角的"设置"图标
    • 或点击左侧导航栏的"设置"菜单

  4. 查看连接详情

    • 在设置页面中找到"连接详情"或"Connection Details"部分
    • 点击"显示 DSN"或"Reveal DSN"按钮
    • 复制显示的 DSN 字符串

注意：DSN 包含敏感信息，请妥善保管，不要泄露。

方法 2: 联系项目管理员

如果您无法访问项目设置页面，可以：

  • 联系项目管理员获取 DSN
  • 通过工单系统申请项目访问权限
  • 联系 APM 平台管理员

DSN 格式说明

内部平台 DSN 格式

内部 Uptrace 平台的 DSN 格式如下：

http://<token>@uptrace-grpc.yodao.cn/<project_id>?grpc=4317

DSN 组成部分

1. 协议（Protocol）

http://

2. Token（令牌）

abc123def456

用于认证的密钥，由平台自动生成。Token 是项目级别的，每个项目有唯一的 Token。

安全提示：

  • Token 具有写入权限，请妥善保管
  • 不要将 Token 提交到版本控制系统
  • 定期检查 Token 的使用情况

3. Endpoint（服务地址）

uptrace-grpc.yodao.cn

内部 Uptrace 平台的服务地址：

  • HTTP 端点: uptrace-grpc.yodao.cn
  • gRPC 端点: uptrace-grpc.yodao.cn:4317

4. Project ID（项目 ID）

1234

项目的唯一标识符，用于区分不同的项目。

5. 可选参数

gRPC 端口:

?grpc=4317

指定 gRPC 协议的端口，用于 OTLP over gRPC 传输。

完整示例

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

这个 DSN 表示：

  • Token 为 abc123def456
  • HTTP 端点为 uptrace-grpc.yodao.cn
  • gRPC 端点为 uptrace-grpc.yodao.cn:4317
  • 项目 ID 为 1234

DSN 配置示例

使用环境变量（推荐）

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

# 设置 DSN
export OTEL_EXPORTER_OTLP_ENDPOINT=uptrace-grpc.yodao.cn:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317


# 或者使用 HTTP 端点
export OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317

使用 gRPC 端点（推荐）

注意：非内网服务接入时，只能使用grpc端点

gRPC 端点性能更好，推荐用于生产环境：

# gRPC 配置
export OTEL_EXPORTER_OTLP_ENDPOINT=uptrace-grpc.yodao.cn:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

使用 HTTP 端点

如果 gRPC 端口被防火墙限制，可以使用 HTTP 端点：

# HTTP 配置
export OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317

不同语言的配置

Go

package main


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


func main() {
    // 从环境变量读取 DSN
    dsn := os.Getenv("UPTRACE_DSN")
    
    uptrace.ConfigureOpentelemetry(
        uptrace.WithDSN(dsn),
        uptrace.WithServiceName("my-service"),
    )
    
    // 或使用标准 OTLP 配置
    os.Setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "uptrace-grpc.yodao.cn:4317")
    os.Setenv("OTEL_EXPORTER_OTLP_PROTOCOL", "grpc")
    os.Setenv("OTEL_EXPORTER_OTLP_HEADERS", "uptrace-dsn=http://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317")
}

Python

import os


# 使用环境变量
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "uptrace-grpc.yodao.cn:4317"
os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "grpc"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = "uptrace-dsn=http://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317"
os.environ["OTEL_SERVICE_NAME"] = "my-service"

Java

# 启动时设置环境变量
export OTEL_EXPORTER_OTLP_ENDPOINT=uptrace-grpc.yodao.cn:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317


# 启动应用
java -javaagent:opentelemetry-javaagent.jar -jar my-app.jar

JavaScript/Node.js

// 使用环境变量
process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'uptrace-grpc.yodao.cn:4317';
process.env.OTEL_EXPORTER_OTLP_PROTOCOL = 'grpc';
process.env.OTEL_EXPORTER_OTLP_HEADERS = 'uptrace-dsn=http://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317';

.NET

// 使用环境变量
Environment.SetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT", "uptrace-grpc.yodao.cn:4317");
Environment.SetEnvironmentVariable("OTEL_EXPORTER_OTLP_PROTOCOL", "grpc");
Environment.SetEnvironmentVariable("OTEL_EXPORTER_OTLP_HEADERS", "uptrace-dsn=http://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317");

环境特定配置

开发环境

# .env.development
OTEL_EXPORTER_OTLP_ENDPOINT=uptrace-grpc.yodao.cn:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://dev-token@uptrace-grpc.yodao.cn/
OTEL_SERVICE_NAME=my-service-dev
OTEL_TRACES_SAMPLER_ARG=1.0  # 100% 采样用于开发

测试环境

# .env.test
OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://test-token@uptrace-grpc.yodao.cn/test-project?grpc=4317
OTEL_SERVICE_NAME=my-service-test
OTEL_TRACES_SAMPLER_ARG=0.5  # 50% 采样

生产环境

# .env.production
OTEL_EXPORTER_OTLP_ENDPOINT=uptrace-grpc.yodao.cn:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://prod-token@uptrace-grpc.yodao.cn/prod-project?grpc=4317
OTEL_SERVICE_NAME=my-service
OTEL_TRACES_SAMPLER_ARG=0.1  # 10% 采样
OTEL_EXPORTER_OTLP_COMPRESSION=gzip

DSN 验证

验证 DSN 格式

可以使用以下方法验证 DSN 格式是否正确：

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


# 检查 DSN 格式
if [[ $DSN =~ ^https://[^@]+@[^/]+/[^?]+ ]]; then
    echo "✓ DSN 格式正确"
    
    # 提取组件
    TOKEN=$(echo "$DSN" | grep -oP '://\K[^@]+')
    ENDPOINT=$(echo "$DSN" | grep -oP '@\K[^/]+')
    PROJECT=$(echo "$DSN" | grep -oP '/\K[^?]+')
    
    echo "Token: ${TOKEN:0:8}..."
    echo "Endpoint: $ENDPOINT"
    echo "Project: $PROJECT"
else
    echo "✗ DSN 格式错误"
    exit 1
fi

测试连接

发送测试数据验证 DSN 是否有效：

# 使用 curl 测试 HTTP 端点
curl -X POST https://uptrace-grpc.yodao.cn/v1/traces \
  -H "Content-Type: application/x-protobuf" \
  -H "uptrace-dsn: https://abc123def456@uptrace-grpc.yodao.cn/1234?grpc=4317" \
  --data-binary @test-trace.pb

常见问题

1. DSN 无效或认证失败

错误信息:

authentication failed: invalid DSN

解决方案:

  • 检查 DSN 格式是否正确
  • 确认 Token 是否有效
  • 检查项目 ID 是否正确
  • 联系项目管理员重新生成 DSN

2. 网络连接问题

错误信息:

failed to connect to endpoint: connection refused

解决方案:

  • 检查 endpoint 地址是否正确：uptrace-grpc.yodao.cn
  • 确认端口是否正确（gRPC: 4317, HTTP: 80）
  • 检查网络连接和防火墙规则
  • 尝试使用 HTTP 端点（端口 80）

3. 权限不足

错误信息:

permission denied: insufficient privileges

解决方案:

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

4. 项目不存在

错误信息:

project not found

解决方案:

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

安全最佳实践

1. 不要硬编码 DSN

❌ 错误做法:

dsn := "http://abc123@uptrace-grpc.yodao.cn/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

4. 定期检查 DSN 使用情况

  • 定期审查 DSN 的使用日志
  • 监控异常的访问模式
  • 发现泄露及时重置 DSN

下一步

参考资源

在Gitlab上编辑本文档