From dc05c93c024c652c410fb1fb430da4cb7442151b Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sun, 26 Apr 2026 03:04:47 -0700 Subject: [PATCH] chore(docker): expose diagnostics observability settings --- .github/workflows/docker-release.yml | 6 +++ docker-compose.yml | 10 +++++ docs/install/docker.md | 58 +++++++++++++++++++++++----- scripts/docker/setup.sh | 18 ++++++++- 4 files changed, 81 insertions(+), 11 deletions(-) diff --git a/.github/workflows/docker-release.yml b/.github/workflows/docker-release.yml index dd8ddb9241a..4af98f336b8 100644 --- a/.github/workflows/docker-release.yml +++ b/.github/workflows/docker-release.yml @@ -159,6 +159,8 @@ jobs: platforms: linux/amd64 cache-from: type=gha,scope=docker-release-amd64 cache-to: type=gha,mode=max,scope=docker-release-amd64 + build-args: | + OPENCLAW_EXTENSIONS=diagnostics-otel tags: ${{ steps.tags.outputs.value }} labels: ${{ steps.labels.outputs.value }} provenance: false @@ -174,6 +176,7 @@ jobs: cache-from: type=gha,scope=docker-release-amd64 cache-to: type=gha,mode=max,scope=docker-release-amd64 build-args: | + OPENCLAW_EXTENSIONS=diagnostics-otel OPENCLAW_VARIANT=slim tags: ${{ steps.tags.outputs.slim }} labels: ${{ steps.labels.outputs.value }} @@ -276,6 +279,8 @@ jobs: platforms: linux/arm64 cache-from: type=gha,scope=docker-release-arm64 cache-to: type=gha,mode=max,scope=docker-release-arm64 + build-args: | + OPENCLAW_EXTENSIONS=diagnostics-otel tags: ${{ steps.tags.outputs.value }} labels: ${{ steps.labels.outputs.value }} provenance: false @@ -291,6 +296,7 @@ jobs: cache-from: type=gha,scope=docker-release-arm64 cache-to: type=gha,mode=max,scope=docker-release-arm64 build-args: | + OPENCLAW_EXTENSIONS=diagnostics-otel OPENCLAW_VARIANT=slim tags: ${{ steps.tags.outputs.slim }} labels: ${{ steps.labels.outputs.value }} diff --git a/docker-compose.yml b/docker-compose.yml index dee895d469a..0d8f1497475 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -9,6 +9,16 @@ services: # Docker bridge networks usually do not carry mDNS multicast reliably. # Set OPENCLAW_DISABLE_BONJOUR=0 only on host/macvlan/mDNS-capable networks. OPENCLAW_DISABLE_BONJOUR: ${OPENCLAW_DISABLE_BONJOUR:-1} + # OpenTelemetry export is outbound OTLP/HTTP from the Gateway. Prometheus + # uses the existing authenticated Gateway route; it does not need a port. + OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-} + OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:-} + OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: ${OTEL_EXPORTER_OTLP_METRICS_ENDPOINT:-} + OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: ${OTEL_EXPORTER_OTLP_LOGS_ENDPOINT:-} + OTEL_EXPORTER_OTLP_PROTOCOL: ${OTEL_EXPORTER_OTLP_PROTOCOL:-http/protobuf} + OTEL_SERVICE_NAME: ${OTEL_SERVICE_NAME:-} + OTEL_SEMCONV_STABILITY_OPT_IN: ${OTEL_SEMCONV_STABILITY_OPT_IN:-} + OPENCLAW_OTEL_PRELOADED: ${OPENCLAW_OTEL_PRELOADED:-} CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-} CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-} CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-} diff --git a/docs/install/docker.md b/docs/install/docker.md index e025cf2a4df..50dac2d6915 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -122,16 +122,54 @@ and setup-time config writes through `openclaw-gateway` with The setup script accepts these optional environment variables: -| Variable | Purpose | -| ------------------------------ | --------------------------------------------------------------- | -| `OPENCLAW_IMAGE` | Use a remote image instead of building locally | -| `OPENCLAW_DOCKER_APT_PACKAGES` | Install extra apt packages during build (space-separated) | -| `OPENCLAW_EXTENSIONS` | Pre-install plugin deps at build time (space-separated names) | -| `OPENCLAW_EXTRA_MOUNTS` | Extra host bind mounts (comma-separated `source:target[:opts]`) | -| `OPENCLAW_HOME_VOLUME` | Persist `/home/node` in a named Docker volume | -| `OPENCLAW_SANDBOX` | Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`) | -| `OPENCLAW_DOCKER_SOCKET` | Override Docker socket path | -| `OPENCLAW_DISABLE_BONJOUR` | Disable Bonjour/mDNS advertising (defaults to `1` for Docker) | +| Variable | Purpose | +| ------------------------------- | --------------------------------------------------------------- | +| `OPENCLAW_IMAGE` | Use a remote image instead of building locally | +| `OPENCLAW_DOCKER_APT_PACKAGES` | Install extra apt packages during build (space-separated) | +| `OPENCLAW_EXTENSIONS` | Pre-install plugin deps at build time (space-separated names) | +| `OPENCLAW_EXTRA_MOUNTS` | Extra host bind mounts (comma-separated `source:target[:opts]`) | +| `OPENCLAW_HOME_VOLUME` | Persist `/home/node` in a named Docker volume | +| `OPENCLAW_SANDBOX` | Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`) | +| `OPENCLAW_DOCKER_SOCKET` | Override Docker socket path | +| `OPENCLAW_DISABLE_BONJOUR` | Disable Bonjour/mDNS advertising (defaults to `1` for Docker) | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Shared OTLP/HTTP collector endpoint for OpenTelemetry export | +| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | Signal-specific OTLP endpoints for traces, metrics, or logs | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP protocol override. Only `http/protobuf` is supported today | +| `OTEL_SERVICE_NAME` | Service name used for OpenTelemetry resources | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Opt in to latest experimental GenAI semantic attributes | +| `OPENCLAW_OTEL_PRELOADED` | Skip starting a second OpenTelemetry SDK when one is preloaded | + +### Observability + +OpenTelemetry export is outbound from the Gateway container to your OTLP +collector. It does not require a published Docker port. If you build the image +locally and want the bundled OpenTelemetry exporter available inside the image, +include its runtime dependencies: + +```bash +export OPENCLAW_EXTENSIONS="diagnostics-otel" +export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318" +export OTEL_SERVICE_NAME="openclaw-gateway" +./scripts/docker/setup.sh +``` + +The official OpenClaw Docker release image includes `diagnostics-otel` +dependencies. To enable export, allow and enable the `diagnostics-otel` plugin +in config, then set `diagnostics.otel.enabled=true` or use the config example in +[OpenTelemetry export](/gateway/opentelemetry). Collector auth headers are +configured through `diagnostics.otel.headers`, not through Docker environment +variables. + +Prometheus metrics use the already-published Gateway port. Enable the +`diagnostics-prometheus` plugin, then scrape: + +```text +http://:18789/api/diagnostics/prometheus +``` + +The route is protected by Gateway authentication. Do not expose a separate +public `/metrics` port or unauthenticated reverse-proxy path. See +[Prometheus metrics](/gateway/prometheus). ### Health checks diff --git a/scripts/docker/setup.sh b/scripts/docker/setup.sh index be076899251..96be3aedfbe 100755 --- a/scripts/docker/setup.sh +++ b/scripts/docker/setup.sh @@ -285,6 +285,14 @@ export OPENCLAW_ALLOW_INSECURE_PRIVATE_WS="${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: export OPENCLAW_SANDBOX="$SANDBOX_ENABLED" export OPENCLAW_DOCKER_SOCKET="$DOCKER_SOCKET_PATH" export OPENCLAW_TZ="$TIMEZONE" +export OTEL_EXPORTER_OTLP_ENDPOINT="${OTEL_EXPORTER_OTLP_ENDPOINT:-}" +export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:-}" +export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="${OTEL_EXPORTER_OTLP_METRICS_ENDPOINT:-}" +export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="${OTEL_EXPORTER_OTLP_LOGS_ENDPOINT:-}" +export OTEL_EXPORTER_OTLP_PROTOCOL="${OTEL_EXPORTER_OTLP_PROTOCOL:-}" +export OTEL_SERVICE_NAME="${OTEL_SERVICE_NAME:-}" +export OTEL_SEMCONV_STABILITY_OPT_IN="${OTEL_SEMCONV_STABILITY_OPT_IN:-}" +export OPENCLAW_OTEL_PRELOADED="${OPENCLAW_OTEL_PRELOADED:-}" # Detect Docker socket GID for sandbox group_add. DOCKER_GID="" @@ -471,7 +479,15 @@ upsert_env "$ENV_FILE" \ DOCKER_GID \ OPENCLAW_INSTALL_DOCKER_CLI \ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS \ - OPENCLAW_TZ + OPENCLAW_TZ \ + OTEL_EXPORTER_OTLP_ENDPOINT \ + OTEL_EXPORTER_OTLP_TRACES_ENDPOINT \ + OTEL_EXPORTER_OTLP_METRICS_ENDPOINT \ + OTEL_EXPORTER_OTLP_LOGS_ENDPOINT \ + OTEL_EXPORTER_OTLP_PROTOCOL \ + OTEL_SERVICE_NAME \ + OTEL_SEMCONV_STABILITY_OPT_IN \ + OPENCLAW_OTEL_PRELOADED if [[ "$IMAGE_NAME" == "openclaw:local" ]]; then echo "==> Building Docker image: $IMAGE_NAME"