Device Telemetry (OTLP Ingest)
Fleet Manager accepts device metrics and logs over the industry-standard OpenTelemetry Protocol (OTLP). A device (or a local collector/agent running alongside it) exports directly to Fleet Manager using its existing device identity — no separate telemetry account or credential is needed.
Who this is for: integrators configuring an edge device’s OpenTelemetry exporter, or anyone evaluating what device observability data Fleet Manager can ingest.
This is a Fleet Manager–native API, not part of Margo. The Margo section of this site covers device onboarding, capability reporting and workload orchestration — telemetry is a separate, independent surface with its own host and its own routes. The one thing the two share is the device certificate: if your device has already completed Margo onboarding, it already holds everything it needs to send telemetry too.
Endpoint
Section titled “Endpoint”https://telemetry.<your-environment-domain>/<tenantSlug>/api/v1/telemetryThe telemetry. host is a sibling of your Fleet Manager application URL,
on the same base domain — not a separate domain to look up. If you access
Fleet Manager at https://fleet-manager.example.com, telemetry ingest is at
https://telemetry.example.com. Ask your administrator if you’re unsure of
your organization’s exact domain.
Configure this as the base endpoint in a standard OTLP/HTTP exporter — it
appends /v1/metrics and /v1/logs itself:
OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.example.com/acme-corp/api/v1/telemetry<tenantSlug> is your organization’s slug — the same one used for device
onboarding.
On-premises/OpenShift deployments: telemetry ingest is off by default
and must be explicitly enabled by the platform administrator. If your
Fleet Manager instance runs on-premises and telemetry data isn’t arriving,
confirm with your administrator that ingest has been enabled and that a TLS
certificate has been provisioned for the telemetry. host — this step is
manual on OpenShift and doesn’t happen automatically.
Authentication
Section titled “Authentication”Telemetry ingest uses mutual TLS with the device’s existing certificate — the same certificate and private key issued during device onboarding. There is no separate telemetry credential to provision or rotate.
- The server presents a publicly trusted certificate (validate against your normal public trust store — this is not the Fleet Manager Root CA used for onboarding).
- TLS 1.3 minimum; SNI is required.
- A certificate that has been revoked is rejected immediately on the next request — there is no delay for cache expiry beyond a few minutes.
Payload format
Section titled “Payload format”Both standard OTLP encodings are accepted — send whichever your exporter uses by default:
Content-Type: application/json— OTLP/JSONContent-Type: application/x-protobuf— OTLP/protobuf (the default for most OpenTelemetry SDKs and collector distributions)
Metrics: only gauge and sum data points are stored today; histogram,
exponentialHistogram and summary are accepted but silently dropped. Prefer
gauges and sums for anything you need visible in the dashboard.
Logs: the log body must be a plain string (stringValue); structured
bodies are not read. Attach service.name as a log-record or data-point
attribute (not a resource attribute) if you want it to appear as the log
source in the Devices view.
Rate limits and payload caps
Section titled “Rate limits and payload caps”To protect the shared platform, ingest is rate-limited per device and per organization, and each request is capped in size and record count:
| Limit | Default |
|---|---|
| Request body size | 4 MB |
| Requests per device | 120 per 60 seconds |
| Requests per organization | 1200 per 60 seconds |
| Metric data points per request | 1000 |
| Log records per request | 500 |
A rate-limit breach returns 429 with a Retry-After header — back off and
retry. Exceeding a per-request record cap does not fail the whole batch: the
records up to the cap are accepted and stored, and the response reports how
many were dropped so you can reduce your batch size.
If your fleet’s expected export volume is close to either rate limit, contact your Fleet Manager administrator — these limits are configurable per deployment.
Recommended: batch on a 10–60 second interval and apply exponential
backoff with jitter on 429 and 5xx responses, regardless of the defaults
above.
Responses and errors
Section titled “Responses and errors”A fully accepted request returns 200 with an empty JSON body. A request
where some records exceeded the per-request cap still returns 200, with an
OTLP partial-success body reporting what was dropped.
| Status | Meaning | What to do |
|---|---|---|
| 200 | Accepted (fully, or partially — check the response) | Continue; reduce batch size if partial |
| 400 | Malformed request body | Fix the payload — retrying unchanged will not help |
| 401 | No certificate presented, or it is unknown/revoked | Check device onboarding/certificate status |
| 403 | Tenant slug does not match the certificate’s org | Fix the configured slug |
| 404 | Unknown or inactive tenant slug | Fix the configured slug |
| 413 | Request body too large | Reduce batch size |
| 415 | Unsupported Content-Type | Use application/json or application/x-protobuf |
| 429 | Rate limited | Back off (honor Retry-After) and retry |
Once telemetry is flowing, view it per device under Devices → Health and in the Dashboard’s fleet health metrics.