docker-otel-lgtm

一个基于 Docker 镜像的 OpenTelemetry 后端。它将 OpenTelemetry Collector、 Prometheus（指标）、Tempo（追踪）、Loki（日志）、Pyroscope（剖析）以及 Grafana 打包到单个容器中——并可选支持 OBI（eBPF 自动插桩）。

Overview of telemetry flow: applications, optionally auto-instrumented with OBI for traces and metrics, send telemetry to the OpenTelemetry Collector, which routes metrics to Prometheus, traces to Tempo, logs to Loki, and profiles to Pyroscope, with all signals visualized in Grafana

The grafana/otel-lgtm Docker image 是一个用于 OpenTelemetry 的开源后端，旨在用于开发、演示和测试环境。

[!IMPORTANT] 如果您正在寻找一个生产就绪、开箱即用的解决方案，用于监控应用程序并利用 OpenTelemetry 和 Prometheus 将 MTTR（平均解决时间）降至最低，您应该尝试 Grafana Cloud Application Observability。

文档

博客文章：
- Docker 镜像中的 OpenTelemetry 后端：介绍 grafana/otel-lgtm
- 5 秒内实现可观测性：回顾 grafana/otel-lgtm 的一年

获取 Docker 镜像

Docker 镜像可在 Docker Hub 上获取。

docker pull grafana/otel-lgtm:latest

运行 Docker 镜像

Linux/Unix

./run-lgtm.sh

Windows（PowerShell）

./run-lgtm

在 Linux/Unix 上使用 mise

你也可以使用 mise 来运行 Docker 镜像：

mise run lgtm

配置

启用日志记录

您可以在 .env 文件中启用日志记录以进行故障排查：

环境变量	启用日志记录的位置：
`ENABLE_LOGS_GRAFANA`	Grafana
`ENABLE_LOGS_LOKI`	Loki
`ENABLE_LOGS_PROMETHEUS`	Prometheus
`ENABLE_LOGS_TEMPO`	Tempo
`ENABLE_LOGS_PYROSCOPE`	Pyroscope
`ENABLE_LOGS_OTELCOL`	OpenTelemetry Collector
`ENABLE_LOGS_OBI`	OBI
`ENABLE_LOGS_ALL`	以上所有

这与任何应用程序日志无关，应用程序日志由 OpenTelemetry 收集。

配置关闭超时

容器将 SIGTERM 和 SIGINT 转发到每个后端，并等待最多五秒以进行优雅关闭。设置 LGTM_SHUTDOWN_TIMEOUT_SECONDS 以更改此宽限期。超时后仍在运行的进程将被强制停止。

启用 OBI（eBPF 自动插桩）

OpenTelemetry eBPF Instrumentation (OBI) 使用 eBPF 自动生成 HTTP/gRPC 服务的追踪和 RED 指标——无需任何代码更改。

要启用 OBI，请在您的 .env 文件中添加 ENABLE_OBI=true，或将其作为环境变量传递：

ENABLE_OBI=true ./run-lgtm.sh

# Using mise
mise run lgtm-obi

要求： 支持 BTF 的 Linux 内核 5.8+。当启用 OBI 时，run-lgtm.sh 和 run-lgtm.ps1 脚本会自动添加所需的 --pid=host 和 --privileged Docker 标志。如果您直接运行 docker run，则必须手动添加这些标志。

[!NOTE] --pid=host 标志使容器与主机共享 PID 命名空间，因此 OBI 可以发现并插桩运行在主机上的进程——而不仅仅是容器内部的进程。例如，OBI_TARGET=java 也会插桩运行在主机上的 Java 进程。

针对特定应用程序

默认情况下，OBI 会在常用端口（80、443、8080-8099、 3000-3999、5000-5999）上发现服务。您可以针对特定应用程序：

# Monitor all Java processes
ENABLE_OBI=true OBI_TARGET=java ./run-lgtm.sh

# Monitor all Python processes
ENABLE_OBI=true OBI_TARGET=python ./run-lgtm.sh

# Monitor a specific executable by name
ENABLE_OBI=true OBI_TARGET=myapp ./run-lgtm.sh

# Monitor specific ports
ENABLE_OBI=true OTEL_EBPF_OPEN_PORT=8080,9090 ./run-lgtm.sh

变量	用途
`OBI_TARGET`	友好的语言目标：`java`、`python`、`node`、`dotnet`、`ruby` 或任意正则表达式
`OTEL_EBPF_OPEN_PORT`	覆盖要监控的端口（原生 OBI 环境变量）
`OTEL_EBPF_AUTO_TARGET_EXE`	可执行文件名模式（原生 OBI 环境变量，由 `OBI_TARGET` 自动设置）

将数据发送到供应商

除了内置的可观测性工具外，您还可以将数据发送到供应商。这样，您可以轻松尝试并在不同的后端之间切换。

如果设置了 OTEL_EXPORTER_OTLP_ENDPOINT 变量，OpenTelemetry Collector 将使用 "OTLP/HTTP" 将数据（日志、指标和追踪）发送到指定的端点。

您还可以配置按信号划分的端点：

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

如果同时设置了全局和每个信号的端点，则每个信号的值优先。端点必须包含协议（例如，http://jaeger:4318）。

此外，您可以提供 OTEL_EXPORTER_OTLP_HEADERS，例如，用于对后端进行身份验证。

将数据发送到 Grafana Cloud

您可以在 Grafana Cloud 账户中找到环境变量的值。

在容器实例化之间持久化数据

仓库中的各个组件被配置为将数据写入 /data 目录。如果需要持久化在创建和销毁容器之间的数据，您可以将卷挂载到 /data 目录。请注意，此镜像旨在用于开发、演示和测试环境，将数据持久化到外部卷不会改变这一点。然而，在某些情况下，此功能对于某些用户即使在测试环境中也可能有用。

自定义后端配置

每个后端都支持一个 *_EXTRA_ARGS 环境变量，用于传递额外的 CLI 标志，而无需修改任何文件：

后端	环境变量	示例
Prometheus	`PROMETHEUS_EXTRA_ARGS`	`--storage.tsdb.retention.time=90d`
Loki	`LOKI_EXTRA_ARGS`	`--limits.retention-period=90d`
Tempo	`TEMPO_EXTRA_ARGS`	`--query-frontend.mcp-server.enabled=true`
Pyroscope	`PYROSCOPE_EXTRA_ARGS`
OpenTelemetry Collector	`OTELCOL_EXTRA_ARGS`

例如，要为 Prometheus 设置 90 天的保留期：

docker run -e PROMETHEUS_EXTRA_ARGS="--storage.tsdb.retention.time=90d" grafana/otel-lgtm

[!NOTE] 该值会按空白字符拆分为独立的参数。对于需要包含空格的值的选项，请改为挂载自定义配置文件（见下文）。

如需进行更深入的自定义，您可以将自定义配置文件挂载到容器中：

Backend	Config file path
Prometheus	`/otel-lgtm/prometheus.yaml`
Loki	`/otel-lgtm/loki-config.yaml`
Tempo	`/otel-lgtm/tempo-config.yaml`
Pyroscope	`/otel-lgtm/pyroscope-config.yaml`
OpenTelemetry Collector	`/otel-lgtm/otelcol-config.yaml`

docker run -v ./my-loki-config.yaml:/otel-lgtm/loki-config.yaml:ro grafana/otel-lgtm

Grafana 通过 GF_* 个环境变量进行配置 — 请参阅 Grafana 文档以获取详细信息。

预安装 Grafana 插件

您可以通过将插件添加到 GF_PLUGINS_PREINSTALL 环境变量来预安装 Grafana 插件。请参阅 Grafana 文档以获取更多信息。

添加自定义仪表板

您可以通过使用 provisioning 配置将自定义 Grafana 仪表板挂载到容器中来添加它们。

创建一个仪表板 JSON 文件和一个 provisioning YAML 文件：

dashboards-provisioning.yaml:

apiVersion: 1

providers:
  - name: "Custom Dashboards"
    type: file
    options:
      path: /otel-lgtm/grafana/conf/provisioning/dashboards/custom
      foldersFromFilesStructure: false

在您的 docker-compose.yml 中挂载这两个文件：

services:
  lgtm:
    image: grafana/otel-lgtm
    volumes:
      - ./custom-dashboard.json:/otel-lgtm/grafana/conf/provisioning/dashboards/custom/custom-dashboard.json:ro
      - ./dashboards-provisioning.yaml:/otel-lgtm/grafana/conf/provisioning/dashboards/custom.yaml:ro

请参阅 Java 示例以获取完整的工作示例。

要将自定义仪表板设置为首页仪表板，请添加 GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH 环境变量：

services:
  lgtm:
    image: grafana/otel-lgtm
    environment:
      GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH: /otel-lgtm/grafana/conf/provisioning/dashboards/custom/custom-dashboard.json

在 Kubernetes 中运行 lgtm

# Create k8s resources
kubectl apply -f k8s/lgtm.yaml

# Configure port forwarding
kubectl port-forward service/lgtm 3000:3000 3200:3200 4040:4040 4317:4317 4318:4318 9090:9090

# Using mise
mise k8s-apply
mise k8s-port-forward

发送 OpenTelemetry 数据

无需配置任何内容：Docker 镜像可直接使用 OpenTelemetry 的默认设置。

# Not needed, but these are the defaults in OpenTelemetry
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318

查看 Grafana

导航至 http://127.0.0.1:3000 并使用默认内置用户 admin 和密码 admin 登录。

从头构建 Docker 镜像

cd docker/
docker build . -t grafana/otel-lgtm

# Using mise
mise build-lgtm

[!TIP] 如果你在本地构建了镜像，你可以使用 run-lgtm 脚本并配合参数 latest true 来运行你的本地镜像（或 mise run local-lgtm）。

构建并运行示例应用

[!TIP] 你可以使用 mise 配合 mise run all 来一起运行所有内容。

运行

运行示例 REST 服务：

在 Unix/Linux 上运行

./run-example.sh

在 Windows 上运行（PowerShell）

./run-example

在 Unix/Linux 上使用 mise 运行

mise run example

生成流量

在 Unix/Linux 上生成

./generate-traffic.sh

在 Windows 上生成（PowerShell）

./generate-traffic

在 Unix/Linux 上使用 mise 生成

mise run generate-traffic

[!TIP] 您可以使用 OTel Checker 来检查插桩是否正确。

以不同语言运行示例应用

示例应用位于 examples/ 目录中。每个示例都有一个 run.sh 或 run.cmd 脚本用于启动应用。

每个示例都实现了一个掷骰子服务，该服务返回 1 到 6 之间的随机数。

每个示例使用不同的应用端口（以便能够同时运行所有应用）。

示例	服务 URL
Java	`curl http://127.0.0.1:8080/rolldice`
Go	`curl http://127.0.0.1:8081/rolldice`
Python	`curl http://127.0.0.1:8082/rolldice`
.NET	`curl http://127.0.0.1:8083/rolldice`
Node.js	`curl http://127.0.0.1:8084/rolldice`

验证容器镜像签名

发布的容器镜像使用 cosign v3+ 进行签名。您可以使用类似于以下示例的命令来验证签名：

VERSION="0.29.0"
IMAGE="docker.io/grafana/otel-lgtm:${VERSION}"
CERTIFICATE_IDENTITY_REGEX="^https://github\.com/grafana/shared-workflows/\.github/workflows/sign-and-attest\.yml@"
CERTIFICATE_OIDC_ISSUER="https://token.actions.githubusercontent.com"
CERTIFICATE_REPO="grafana/docker-otel-lgtm"

cosign verify "${IMAGE}" --certificate-identity-regexp "${CERTIFICATE_IDENTITY_REGEX}" --certificate-oidc-issuer "${CERTIFICATE_OIDC_ISSUER}" --certificate-github-workflow-repository "${CERTIFICATE_REPO}"

也可以验证从我们的持续集成发布到 GitHub Container Registry 的镜像签名。例如，对于 main 分支：

VERSION="main"
IMAGE="ghcr.io/grafana/docker-otel-lgtm:${VERSION}"
WORKFLOW="ghcr-image-build-and-publish.yml"
CERTIFICATE_IDENTITY="https://github.com/grafana/docker-otel-lgtm/.github/workflows/${WORKFLOW}@refs/heads/${VERSION}"
CERTIFICATE_OIDC_ISSUER="https://token.actions.githubusercontent.com"

cosign verify "${IMAGE}" --certificate-identity "${CERTIFICATE_IDENTITY}" --certificate-oidc-issuer "${CERTIFICATE_OIDC_ISSUER}"

验证容器镜像证明

发布的容器镜像也经过了证明。您可以使用 GitHub CLI 验证这些证明，如下例所示：

VERSION="0.29.0"
IMAGE="oci://docker.io/grafana/otel-lgtm:${VERSION}"
REPOSITORY="grafana/docker-otel-lgtm"
SIGNER_WORKFLOW="grafana/shared-workflows/.github/workflows/sign-and-attest.yml"

gh attestation verify --repo "${REPOSITORY}" "${IMAGE}" --signer-workflow "${SIGNER_WORKFLOW}"

也可以验证发布到 GitHub Container Registry 的来自我们持续集成的镜像的签名。例如，对于 main 分支：

VERSION="main"
REPOSITORY="grafana/docker-otel-lgtm"
IMAGE="oci://ghcr.io/${REPOSITORY}:${VERSION}"

gh attestation verify --repo "${REPOSITORY}" "${IMAGE}"

AI 工具集成 (MCP)

该技术栈提供了 MCP 集成，使 AI 编码工具能够查询日志、指标、追踪和仪表盘。可以通过 Tempo 的 HTTP MCP 端点或客户端 Grafana MCP 服务器 (uvx mcp-grafana) 查询追踪，后者还提供对仪表盘、日志和指标的访问。

通过设置环境变量启用 Tempo MCP 服务器：

TEMPO_EXTRA_ARGS="--query-frontend.mcp-server.enabled=true"

docker run -e TEMPO_EXTRA_ARGS="--query-frontend.mcp-server.enabled=true" grafana/otel-lgtm

docker exec lgtm cat /etc/lgtm/mcp.json   # or: podman exec ...
# Kubernetes: kubectl exec deploy/lgtm -- cat /etc/lgtm/mcp.json

将 JSON 粘贴到 AI 工具的 MCP 配置中。有关详细信息，请参阅 docs/mcp-integration.md。