Telemetry

Your terminal sends its logs to Konsol as OpenTelemetry over OTLP/HTTP. Konsol keeps them so support can see what the terminal was doing when a problem occurred.

EndpointCopy Anchor Link

Set the logs endpoint (OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) to the full URL above, or set the base endpoint (OTEL_EXPORTER_OTLP_ENDPOINT) to https://device.konsol.my/device/v1/telemetry and let the SDK append /v1/logs. Konsol accepts logs only. It does not collect traces or metrics, and does not accept OTLP over gRPC.

Send OTLP protobuf (Content-Type: application/x-protobuf) or OTLP JSON (Content-Type: application/json). Either can be gzip-compressed.

AuthenticationCopy Anchor Link

Send the terminal's device token, as on every other Device API request:

Authorization: Bearer dvc_<prefix>_<secret>

Konsol returns 401 if the token is missing, revoked or unknown, or if the terminal is decommissioned. A suspended terminal can still send logs.

Konsol uses the token to file the records under the terminal's organisation. To let support tell your terminals apart, add the terminal's serial number as a resource attribute, such as host.id.

LimitsCopy Anchor Link

Batch records into few, larger requests. Konsol does not buffer telemetry, so the terminal must keep each batch until it is accepted.

• On a 429, a 5xx or a dropped connection, keep the records and retry with backoff.
• On a 413, split the batch. The 1 MiB limit applies to the body as sent, after compression.

ContentCopy Anchor Link

Never log card data, PINs or keys. As a safeguard, Konsol masks standalone runs of 13 to 19 digits in log text and attribute values. Your terminal must still never send them.

ExampleCopy Anchor Link

With an OpenTelemetry SDK:

OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://device.konsol.my/device/v1/telemetry/v1/logs
OTEL_EXPORTER_OTLP_LOGS_HEADERS="Authorization=Bearer%20dvc_<prefix>_<secret>"
OTEL_TRACES_EXPORTER=none
OTEL_METRICS_EXPORTER=none

The header value is percent-encoded: %20 is the space. The OpenTelemetry specification requires this for OTEL_EXPORTER_OTLP_LOGS_HEADERS.

Or by hand:

curl -X POST https://device.konsol.my/device/v1/telemetry/v1/logs \
  -H 'Authorization: Bearer dvc_<prefix>_<secret>' \
  -H 'Content-Type: application/json' \
  -d '{"resourceLogs": [{
        "resource": {"attributes": [
          {"key": "service.name", "value": {"stringValue": "acme-pos"}},
          {"key": "host.id", "value": {"stringValue": "SN-0001"}}
        ]},
        "scopeLogs": [{"logRecords": [{
          "timeUnixNano": "1792137600000000000",
          "severityNumber": 9,
          "severityText": "INFO",
          "body": {"stringValue": "payment app started"}
        }]}]
      }]}'

A 200 response means Konsol accepted the records.