快速开始
三行代码，把第一个指标送上观澜数据。本文使用 Node.js SDK，其他语言请参考对应 SDK 章节。
1. 接入前准备
开始之前，确认这三件事已经就绪：
- 一个观澜项目：提交邮箱后由人工开通（工作日平均 10 分钟），开通邮件内含控制台访问地址。
- 一个 API Key：在控制台「设置 - 密钥管理」创建，可随时轮换。请通过环境变量注入，不要写入代码仓库。
- 出网连通：需要能访问下表中的接入地址，防火墙无需开放入站端口。
| 地址 | 用途 | 协议 |
|---|---|---|
| ingest.guanlan-data.com:443 | 指标、日志与链路数据上报 | HTTPS / gRPC / OTLP |
| api.guanlan-data.com:443 | 查询与管理 API | HTTPS |
| console.guanlan-data.com | 控制台 | HTTPS |
建议先接入一个非核心服务的 5 - 10 个指标，确认链路通畅、标签口径正确后再全量接入。接入过程中遇到问题，可参考帮助中心的排查清单。
2. 安装 SDK
推荐使用包管理器安装官方 SDK：
# npm npm install @guanlan/sdk # pnpm pnpm add @guanlan/sdk
3. 初始化客户端
在控制台创建项目并复制 API Key，然后在应用入口初始化：
import { Guanlan } from '@guanlan/sdk'; const gl = new Guanlan({ apiKey: process.env.GUANLAN_API_KEY, service: 'order-api', // 服务名，作为默认标签 environment: 'production', });
API Key 请通过环境变量注入，不要硬编码在代码仓库中。控制台支持一键轮换 Key。
4. 上报第一个指标
gl.metric('order.created', 1, { channel: 'app', region: 'cn-shanghai', }); // 计数器、直方图、仪表盘均支持 gl.metric('checkout.duration', 342, { unit: 'ms' });
上报是异步批量的，SDK 默认每 5 秒或累计 500 条刷新一次，不会阻塞业务线程。
5. 上报日志
日志与指标走同一条采集管道，已有 OpenTelemetry Collector 的环境可以直接转发：
gl.log('order.failed', { level: 'error', service: 'order-api', traceId: ctx.traceId, // 关联后可从日志直达调用链 detail: { orderId, reason: 'payment_timeout' }, });
单条日志上限 256 KB，超出部分会被截断并计入上报失败计数。结构化字段自动建立索引，正文内容走全文检索。
6. 链路追踪
// 入口创建 span，SDK 自动传播 W3C traceparent await gl.trace('checkout', async (span) => { span.setAttribute('cart.items', cart.length); const order = await span.child('order.create', createOrder); await span.child('payment.charge', () => charge(order)); });
自动埋点覆盖常见 HTTP、gRPC 与数据库客户端，无需改动业务调用结构；若已有 OpenTelemetry SDK，链路数据会在观澜侧与现有 trace 合并。
7. 查询语言
查询语言兼容 PromQL，你可以直接用熟悉的语法：
# 最近 1 小时各渠道的下单量 sum by (channel) ( increase(order_created_total{service="order-api"}[1h]) )
8. API 参考
所有控制台能力均开放 REST API。基地址为 https://api.guanlan-data.com/v2，认证使用 Authorization: Bearer <API_KEY>。
# 查询指标 curl https://api.guanlan-data.com/v2/metrics/query \ -H "Authorization: Bearer $GUANLAN_API_KEY" \ -d 'query=sum(rate(order_created_total[5m]))'
| 端点 | 方法 | 说明 |
|---|---|---|
| /v2/metrics/query | POST | PromQL 即时查询 |
| /v2/metrics/ingest | POST | 批量上报指标 |
| /v2/logs/search | POST | 日志全文检索 |
| /v2/alerts/rules | GET / POST | 告警规则管理 |
9. 配额与限流
以下为默认限制，企业版可按需调整：
| 项目 | 免费版 | 专业版 | 企业版 |
|---|---|---|---|
| 写入限流 | 20 QPS | 500 QPS | 按需调整 |
| 查询限流 | 50 QPS | 1,000 QPS | 按需调整 |
| 单次批量 | 指标与日志单次最多 1,000 条；单条日志上限 256 KB | ||
| 标签基数 | 单个指标建议不超过 100 个标签值，超出后会计入基数告警 | ||
| 最小采样间隔 | 10 秒，低于该间隔的采集请求会被拒绝 | ||
| 超出配额 | 按 ¥0.35/GB 继续计费，不会停止服务 | ||
用量在控制台「用量」页实时更新（每小时同步一次），达到 80% 额度时邮件提醒，并可设置月度预算上限。
10. SDK 语言支持
| 语言 | 安装包 | 最低版本 | 支持能力 |
|---|---|---|---|
| Java | com.guanlan:sdk | 2.0 | 指标 / 日志 / 链路 |
| Go | github.com/guanlan/sdk-go | v2.0.0 | 指标 / 日志 / 链路 |
| Python | guanlan-sdk | 2.0 | 指标 / 日志 / 链路 |
| Node.js | @guanlan/sdk | 2.0 | 指标 / 日志 |
| Rust | guanlan-sdk | 2.0 | 指标 |
| 任意语言 | OpenTelemetry Collector / OTLP HTTP | — | 指标 / 日志 / 链路 |
没有合适的语言时，直接用 OTLP HTTP 推送即可，无需等待官方 SDK。接入端点见接入前准备。
11. 核心概念
- 项目（Project）：资源与权限的顶层边界，通常对应一个团队或一个业务线。
- 服务（Service）：数据归属的最小单元，建议与部署单元一一对应。
- 仪表盘（Dashboard）：图表的集合，支持变量模板与下钻联动。
- 事件（Event）：一次告警的完整生命周期，包含聚合后的相关信号。