Deploying OpenTelemetry Collector at the Edge with Jaeger Export and OpenClaw Token Bucket Trace Analysis

OpenTelemetry is an open‑source observability framework that standardizes the collection of traces, metrics, and logs. Paired with Jaeger, a popular distributed tracing system, it provides a powerful stack for visualizing request flows across microservices.

When you run the OpenClaw Rating API at the edge—close to your users—you reduce latency and improve reliability. However, edge deployments also demand lightweight, secure observability solutions. Deploying the OpenTelemetry Collector at the edge satisfies this need by acting as a local agent that forwards data to a central Jaeger instance for deep analysis.

In this guide we’ll walk through the entire process: from provisioning a minimal runtime, deploying the collector, configuring secure export to Jaeger, instrumenting the token‑bucket logic, to finally analyzing traces in the Jaeger UI.

Choosing a lightweight runtime

For edge nodes, you typically have three options:

• Docker: Fast to start, portable, and works on most edge devices.
• Kubernetes (k3s): Ideal if you already run other microservices on the same node.
• Native binary: Smallest footprint; download the collector binary directly.

Step‑by‑step deployment script (Docker)

# Pull the official OpenTelemetry Collector image
docker pull otel/opentelemetry-collector:latest

# Create a directory for the collector config
mkdir -p /opt/otel/config

# Write the collector.yaml (see next section for details)
cat > /opt/otel/config/collector.yaml <<EOF
# collector.yaml placeholder – will be replaced later
EOF

# Run the collector as a detached container
docker run -d \
  --name otel-collector \
  -p 4317:4317 \   # OTLP gRPC
  -p 55681:55681 \ # OTLP HTTP
  -v /opt/otel/config/collector.yaml:/etc/otel-collector-config.yaml \
  otel/opentelemetry-collector:latest \
  --config /etc/otel-collector-config.yaml

If you prefer Kubernetes, replace the docker run command with a Deployment manifest that mounts the same collector.yaml as a ConfigMap.

Running the collector as a native binary

Download the binary for your OS from the GitHub releases page, place the collector.yaml beside it, and start with ./otelcol --config collector.yaml.

Collector configuration YAML

receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  jaeger:
    endpoint: "jaeger-collector:14250"
    tls:
      insecure: false
      ca_file: "/etc/otel/certs/ca.crt"
      cert_file: "/etc/otel/certs/client.crt"
      key_file: "/etc/otel/certs/client.key"

processors:
  batch:
    timeout: 5s
    send_batch_max_size: 1024

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [jaeger]

This configuration does three things:

• Receives OTLP data over gRPC and HTTP.
• Batches traces to reduce network overhead.
• Exports securely to a Jaeger collector using TLS.

Securing communication

Generate a self‑signed CA and client certificates, then mount them into the container:

# Example using OpenSSL
openssl req -x509 -newkey rsa:4096 -keyout ca.key -out ca.crt -days 365 -nodes -subj "/CN=otel-ca"
openssl req -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj "/CN=otel-client"
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365

# Mount into Docker
docker run -d \
  -v /opt/otel/certs:/etc/otel/certs \
  ... (rest of the run command)

For production, consider using a managed PKI service or integrate with UBOS’s Workflow automation studio to rotate certificates automatically.

Adding OpenTelemetry SDK

Below is a minimal Node.js example. Adjust the language‑specific SDK as needed.

// npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-grpc
const { NodeTracerProvider } = require("@opentelemetry/sdk-node");
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-grpc");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");

// Initialize tracer provider
const provider = new NodeTracerProvider();
const exporter = new OTLPTraceExporter({
  url: "grpc://localhost:4317", // Edge collector endpoint
});
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();

// Optional: auto‑instrument HTTP & Express
registerInstrumentations({
  instrumentations: [
    // add desired instrumentations here
  ],
});

const tracer = provider.getTracer("openclaw-token-bucket");

// Token bucket implementation
function tokenBucket(limit, intervalMs) {
  let tokens = limit;
  setInterval(() => (tokens = limit), intervalMs);
  return {
    tryConsume: () => {
      const span = tracer.startSpan("token_bucket.consume");
      if (tokens > 0) {
        tokens--;
        span.setAttribute("token.bucket.status", "granted");
        span.end();
        return true;
      } else {
        span.setAttribute("token.bucket.status", "rejected");
        span.end();
        return false;
      }
    },
  };
}

// Export for API usage
module.exports = tokenBucket;

Capturing token bucket metrics & traces

In addition to spans, you can emit metrics using the OpenTelemetry Metrics SDK. For example, record the current token count every second and export to a Prometheus endpoint that Jaeger can reference via Prometheus.

When a request hits the OpenClaw Rating API, wrap the handler with a parent span:

app.post("/rate", async (req, res) => {
  const parentSpan = tracer.startSpan("openclaw.rating.request", {
    attributes: {
      "http.method": req.method,
      "http.url": req.originalUrl,
      "user.id": req.body.userId,
    },
  });

  const bucket = tokenBucket(100, 60000); // 100 tokens per minute
  if (!bucket.tryConsume()) {
    parentSpan.setAttribute("rate.limited", true);
    parentSpan.end();
    return res.status(429).send({ error: "Rate limit exceeded" });
  }

  // Simulate rating logic
  const rating = await computeRating(req.body);
  parentSpan.setAttribute("rating.value", rating);
  parentSpan.end();
  res.send({ rating });
});

These spans will flow to the edge collector, be batched, and finally appear in Jaeger as a hierarchy: openclaw.rating.request → token_bucket.consume.

Viewing traces in Jaeger UI

Open the Jaeger UI (usually http://:16686) and search using the service name openclaw-rating-api. You’ll see a list of trace IDs; clicking one expands the timeline.

• Root span: openclaw.rating.request – shows request latency, HTTP attributes, and rate‑limit flag.
• Child span: token_bucket.consume – indicates whether a token was granted or rejected.
• Additional spans (e.g., DB queries, external calls) can be added later for deeper insight.

Correlating token bucket events with request latency

Use Jaeger’s Trace Search filters to isolate rejected requests:

1. Enter token.bucket.status:rejected in the tag filter.
2. Observe the average latency for rejected vs. granted requests.
3. Identify spikes where the token bucket empties too quickly, prompting a capacity adjustment.

Export the filtered data as JSON for further analysis or feed it into UBOS’s AI SEO Analyzer to generate automated reports for stakeholders.

Common pitfalls

• Collector not reachable: Verify that the edge node can resolve the Jaeger hostname and that TLS certificates are correctly mounted.
• Missing spans: Ensure the SDK is initialized before any request handling code runs.
• High CPU usage: Reduce the batch size or increase the batch timeout in the collector config.

Performance tuning tips

• Run the collector with --mem-limit-mib=128 to cap memory on constrained edge devices.
• Enable resource_attributes to add static tags (e.g., edge.location) for easier filtering.
• Leverage UBOS’s Enterprise AI platform to aggregate traces from multiple edge nodes into a single Jaeger cluster.

Observability hygiene

Adopt the following routine:

1. Validate collector health via GET /healthz endpoint.
2. Rotate TLS certificates every 90 days using the Workflow automation studio.
3. Review Jaeger dashboards weekly to spot abnormal latency patterns.