中文
|
English
# OpenTelemetry OTLP 接入
DataBuff 是开源、AI 原生的 OpenTelemetry APM 后端。**Ingest** 服务通过 **OTLP**（OpenTelemetry Protocol）接收遥测数据，供 Web 端做链路追踪、服务指标、拓扑与 AI 排障。
## 支持的信号
| 信号 | OTLP gRPC (4317) | OTLP HTTP (4318) |
|------|------------------|------------------|
| Trace | 支持 | 支持（`/v1/traces`） |
| Metrics | 支持 | 支持（`/v1/metrics`） |
| Logs | 支持 | 支持（`/v1/logs`） |
## 压缩（Compression）
OTLP exporter / otel-collector **默认开启 `gzip` 压缩**。DataBuff Ingest 已支持下列算法，**无需再配置 `compression: none`**。
| 协议 | 支持的压缩 |
|------|------------|
| OTLP/gRPC | `none`、`gzip`（默认）、`snappy`、`zstd` |
| OTLP/HTTP | `none`、`gzip`（默认）、`zstd`、`zlib`、`deflate`、`snappy`、`x-snappy-framed`、`lz4` |
Collector 示例（可省略 `compression`，使用默认 gzip）：
```yaml
exporters:
otlp:
endpoint: ":4317"
tls:
insecure: true
# compression: gzip # 默认；也可改为 snappy / zstd / none
otlphttp:
endpoint: "http://:4318"
# compression: gzip
```
## 前置条件
先完成 Docker 或 Kubernetes 安装，确认 **Ingest** 可达及 OTLP 端口（默认 **4317** gRPC、**4318** HTTP）。
- [Docker 安装](快速入门/docker安装部署.md)
- [Kubernetes 安装](快速入门/k8s安装部署.md)
- [在线演示](https://demo.databuff.ai)
## 接入地址
将 `` 替换为 Ingest 所在主机名或 IP（与安装脚本输出一致）。
| 协议 | 地址 | 说明 |
|------|------|------|
| OTLP/gRPC | `:4317` | 推荐 Agent / Collector 使用 |
| OTLP/HTTP | `http://:4318` | 按信号配置时可使用 `/v1/traces`、`/v1/metrics` |
Docker 默认安装会在宿主机暴露上述端口。
## 应用 SDK（环境变量）
```bash
export OTEL_EXPORTER_OTLP_ENDPOINT="http://:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
# gRPC 示例：
# export OTEL_EXPORTER_OTLP_ENDPOINT="http://:4317"
# export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_SERVICE_NAME="my-service"
```
## OpenTelemetry Collector
```yaml
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
exporters:
otlp:
endpoint: ":4317"
tls:
insecure: true
service:
pipelines:
traces:
receivers: [otlp]
exporters: [otlp]
metrics:
receivers: [otlp]
exporters: [otlp]
logs:
receivers: [otlp]
exporters: [otlp]
```
上报 Logs 时，SDK 可设置：
```bash
export OTEL_LOGS_EXPORTER=otlp
```
## 验证
1. 可选安装 [Demo 应用](快速入门/docker安装部署.md#_3-安装-demo-可选)，持续上报 Trace。
2. 打开 Web UI（`http://:27403`），在应用性能中查看服务与链路。
深入了解数据如何写入与查询，见 [遥测数据流与存储](架构设计/遥测数据流.md)。
## 相关文档
- [eBPF 接入](使用手册/eBPF接入.md) — OBI DaemonSet，无侵入采集 HTTP / gRPC
- [Nginx 接入](使用手册/Nginx接入.md) — `ngx_otel_module` 上报入口 Trace
- [Spring Boot OTLP 接入](快速入门/spring-boot-otlp-integration.md)
- [SkyWalking 接入](使用手册/SkyWalking接入.md)
## 开源信息
- 仓库：[github.com/databufflabs/databuff](https://github.com/databufflabs/databuff)
- 许可证：[AGPL-3.0](https://github.com/databufflabs/databuff/blob/main/LICENSE)