Onboarding Metrics, Logs, and Traces to 炬鲸 with the OpenTelemetry Collector

Why a Collector instead of direct connections

In the OpenTelemetry ecosystem, applications instrument with SDKs while data lands via the Collector. The Collector is a standalone process that receives and forwards telemetry, and it earns its place for three reasons: it decouples "how the app instruments" from "where the data goes", so changing backends never touches application code; it can apply sampling, redaction and rate limiting at the ingress, saving real bandwidth; and it ships with dozens of receivers and exporters, so one copy of data can fan out to several backends.

For 炬鲸 the recommended architecture is app SDK → Collector (OTLP) → 炬鲸. Direct connections work but skip sampling and buffering, which we don't advise for production.

Prerequisites

Check your versions first. Use an official Collector release (this guide uses otelcol-contrib 0.9x, which bundles more receivers). On the 炬鲸 side you need three things:

• OTLP endpoint: https://otlp.ob.jjhub.cn (gRPC 4317 / HTTP 4318)
• Auth token: created under "接入管理 → OpenTelemetry" in the console, in the form jj_xxxxxxxx
• Tenant ID: only for multi-tenant deployments, written into resource attributes; otherwise the default platform is used.

Collector configuration

Here's a minimal working config that receives all three signal types over OTLP and exports them to 炬鲸:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s
    send_batch_size: 512

exporters:
  otlphttp:
    endpoint: https://otlp.ob.jjhub.cn
    headers:
      Authorization: "Bearer jj_xxxxxxxx"
  retry_on_failure:
    enabled: true
    initial_interval: 5s

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

A few notes:

• The otlphttp exporter over HTTP/4318 is easier to get through corporate proxies; if your internal network connects cleanly you can swap in the otlp exporter over 4317.
• The batch processor is not optional. It buffers telemetry and cuts the number of outbound requests by an order of magnitude.
• Turn on retry_on_failure — by default the Collector drops data on network errors.

Pointing your app at the Collector

Application-side changes are minimal: point the OTLP endpoint at the Collector. For Java, set environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector-host:4318
OTEL_SERVICE_NAME=order-service

At startup the SDK sends traces and metrics over OTLP to the Collector automatically. For logs, prefer the OTLP log protocol, or use the filelog receiver to tail existing log files and forward them as OTLP, which avoids invasive code changes.

Worth configuring: resource attributes

Resource attributes are how 炬鲸 tells your environments apart. Set them once in the SDK or via a resource processor in the Collector, and every span, metric and log carries them:

processors:
  resource:
    attributes:
      - key: deployment.environment
        value: prod
        action: upsert

The standard attributes we rely on: service.name (required), deployment.environment, and service.version. With these in place you can filter and alert by environment across all three signal types instead of configuring each one separately.

Verification and troubleshooting

Verify in this order:

1. Check the Collector's own logs for 401/403 (bad token) or connection refused (unreachable endpoint) on the exporter.
2. In 炬鲸 under "链路追踪", filter by service name and confirm traces from the last 5 minutes appear.
3. Under "监控指标", check that the service.name dimension shows up, which means the resource attribute is attached.
4. Under "日志检索", query otel.source and confirm the value is collector.

Common errors: 401 Unauthorized usually means an expired token or a stray space when copying it; context deadline exceeded usually means the network can't reach the endpoint, so curl -v it first; data present but incomplete usually means the sampling rate is too high — check the SDK sampler config.

Once these steps pass, all three signal types flow into 炬鲸 over OTLP. Adding a new service later only requires setting OTEL_EXPORTER_OTLP_ENDPOINT in the new app — nothing changes on the Collector or 炬鲸 side.

Before rolling this out broadly, set three production defaults: keep retry_on_failure and batch on, pin a sampling rate (start at 10% for traces and adjust from there), and rotate the auth token on a schedule. With those in place the pipeline is safe to leave unattended.