OpenTelemetry Monitor

Send OTLP metrics to BlackTide directly from your application SDKs or an OpenTelemetry Collector. Works over HTTP and gRPC and uses the same btm_ bearer tokens as the Prometheus monitor.

What is an OpenTelemetry Monitor?

An OpenTelemetry Monitor ingests metrics emitted by your services using the standard OTLP protocol. BlackTide validates your token, records the samples, and transitions the monitor to down if your exporter stops pushing within the expected interval.

Choose this monitor when you already instrument services with an OpenTelemetry SDK (Go, Python, Node.js, Java, .NET, Rust…) or run an OTEL Collector as part of your stack. If you are still on a classic Prometheus exporter, the Prometheus Monitoruses the same token model over remote_write.

Configuration Options

Ingestion Endpoints

All endpoints require the bearer header Authorization: Bearer btm_…. HTTP is the easiest to troubleshoot (it shows up in regular HTTP logs); gRPC delivers marginally higher throughput for very high-cardinality workloads.

Using the OpenTelemetry Collector

The most common setup: run a local OTEL Collector that scrapes or receives metrics, and forward them to BlackTide through the otlphttp exporter.

exporters:
  otlphttp:
    endpoint: "https://api.blacktide.xyz"
    headers:
      Authorization: "Bearer btm_YOUR_TOKEN_HERE"

service:
  pipelines:
    metrics:
      receivers: [otlp, prometheus]
      processors: [batch]
      exporters: [otlphttp]

The Collector will automatically POST batches to /v1/metrics on the configuredendpoint. No extra path needs to be specified.

Direct SDK Usage

Go

import (
    "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp"
    "go.opentelemetry.io/otel/sdk/metric"
)

exporter, _ := otlpmetrichttp.New(ctx,
    otlpmetrichttp.WithEndpoint("api.blacktide.xyz"),
    otlpmetrichttp.WithURLPath("/v1/metrics"),
    otlpmetrichttp.WithHeaders(map[string]string{
        "Authorization": "Bearer btm_YOUR_TOKEN_HERE",
    }),
)

reader := metric.NewPeriodicReader(exporter)
provider := metric.NewMeterProvider(metric.WithReader(reader))

Python

from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

exporter = OTLPMetricExporter(
    endpoint="https://api.blacktide.xyz/v1/metrics",
    headers={"Authorization": "Bearer btm_YOUR_TOKEN_HERE"},
)

reader = PeriodicExportingMetricReader(exporter, export_interval_millis=60_000)
provider = MeterProvider(metric_readers=[reader])

Node.js

import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';

const exporter = new OTLPMetricExporter({
    url: 'https://api.blacktide.xyz/v1/metrics',
    headers: {
        Authorization: 'Bearer btm_YOUR_TOKEN_HERE',
    },
});

const reader = new PeriodicExportingMetricReader({
    exporter,
    exportIntervalMillis: 60_000,
});

const provider = new MeterProvider({ readers: [reader] });

Environment Variables (all SDKs)

Every OTEL SDK respects the standard env vars. If you prefer config-free code:

OTEL_EXPORTER_OTLP_ENDPOINT=https://api.blacktide.xyz
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer btm_YOUR_TOKEN_HERE
OTEL_METRICS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf

Payload Limits

• Compressed body: 5 MB max per request
• Decompressed body: 50 MB max per request
• Attribute value length: 1024 characters max
• Samples per second: Enforced per token (see your plan on the Pricing page)

Exporters receive 429 Too Many Requests when quotas are exceeded. All official OTEL SDKs retry with exponential backoff; reduce the export interval or enable abatch processor with larger batches to stay below the limit.

When Alerts Fire

The monitor transitions to down when no samples arrive withinexpectedPushIntervalSeconds. Typical causes:

• Your service was redeployed without the OTEL env vars
• The Collector or SDK exporter is failing silently (check its own logs first)
• Token was revoked or workspace downgraded past quota
• Network egress blocked to api.blacktide.xyz

Getting a Metric Token

1. Go to Settings → Metric Tokens
2. Click Create token, pick a name (e.g. prod-otel)
3. Copy the btm_… value — it is only shown once
4. Set it as the Authorization: Bearer header on your exporter

Troubleshooting

401 Unauthorized

The token is missing, malformed, or revoked. Confirm the header is exactlyAuthorization: Bearer btm_… (case-sensitive scheme, single space) and that the token still exists in Settings → Metric Tokens.

404 Not Found

HTTP path mismatch. OTLP/HTTP requires /v1/metrics. If you pointed the SDK at https://api.blacktide.xyz without a path, make sure the SDK is configured to append /v1/metrics (Go needs WithURLPath, most other SDKs add it automatically).

gRPC connection reset

gRPC requires TLS (port 4317 uses TLS, not plaintext). Ensure the SDK is not set to useWithInsecure() in production.

Next Steps

• Prometheus Monitor: remote_write alternative with the same token model
• Alert Rules for push-interval and downtime notifications
• Heartbeat Monitor: single-signal push option for cron jobs