OpenTelemetry

Zharp takes OpenTelemetry traces and logs over OTLP/HTTP. Any language with an OpenTelemetry SDK, and any Collector, can send to it without a Zharp SDK.

The Zharp SDKs are themselves OpenTelemetry underneath, so this page is also the reference for what they send. To set up an app, add it in App Telemetry with the OpenTelemetry platform: the setup page fills in the key and service name for you.

Endpoint and headers

Metrics aren't taken here. The key is an app key (zpk_…) or a workspace API key that can ingest; see Keys for the difference.

Any OpenTelemetry SDK

Every OpenTelemetry SDK reads these environment variables. Traces and logs both go over OTLP/HTTP:

OTEL_EXPORTER_OTLP_ENDPOINT=https://api.zharp.io/api/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer zpk_…
OTEL_SERVICE_NAME=checkout-api
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production

The exporter adds /v1/traces and /v1/logs to the endpoint itself. Some SDKs default to gRPC; set the protocol:

OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf   # or http/json — not grpc

Then turn on your language's instrumentations for your framework, HTTP client and database. To link the app to a Zharp front end, keep the default propagators — tracecontext and baggage — and copy enduser.id and session.id from baggage onto your spans and logs (OpenTelemetry's baggage span processor does this where your language has one).

OpenTelemetry Collector

Add an exporter, then add it to your traces and logs pipelines:

exporters:
  otlphttp/zharp:
    endpoint: https://api.zharp.io/api/v1/otlp
    headers:
      Authorization: Bearer zpk_…

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

A Collector usually sends for several services. Use a workspace API key with Ingest only ticked, and each service's service.name picks its app — new ones appear as discovered apps. With an app key, everything goes to that one app.

Attributes Zharp reads

Attributes are read from the record first, then its resource, and follow the OpenTelemetry semantic conventions. Everything else you send is kept and shown with the span or log.

Requests are the spans of kind SERVER and the spans with no parent (a page load, a screen, a job); one with status ERROR is a failed request. Log levels come from severityNumber (9 info, 13 warn, 17 error, 21 fatal), or from severityText when the number is missing.

How errors are detected

An error event — the thing grouped into issues — is any of:

• A span event named exception with exception.type, exception.message and exception.stacktrace — what span.recordException() writes in every OpenTelemetry SDK.
• A log record with any of those exception.* attributes.

{
  "name": "exception",
  "attributes": [
    { "key": "exception.type", "value": { "stringValue": "PaymentError" } },
    { "key": "exception.message", "value": { "stringValue": "Card declined" } },
    { "key": "exception.stacktrace", "value": { "stringValue": "PaymentError: Card declined\n    at charge (src/pay.js:42:11)\n…" } },
    { "key": "zharp.handled", "value": { "stringValue": "true" } }
  ]
}

• zharp.handled "true" marks one your code caught; anything else is shown as unhandled. OpenTelemetry's exception.escaped false means handled too.
• Send the stack trace as the language prints it, with Type: message on the first line. Zharp recognises the frame formats of JavaScript, Python, Go, Java and Kotlin, PHP, Dart and Apple crash reports, and groups by your own frames.
• Record the exception on the span it happened in, so the issue links to its trace.

Responses

Try it with curl

curl https://api.zharp.io/api/v1/otlp/v1/logs \
  -H "Authorization: Bearer zpk_…" \
  -H "Content-Type: application/json" \
  -d '{"resourceLogs":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"checkout-api"}}]},
       "scopeLogs":[{"logRecords":[{"severityNumber":9,"body":{"stringValue":"Hello from curl"}}]}]}]}'