Skip to content

OpenTelemetry SDKs

Instrument your applications with the standard, off-the-shelf OpenTelemetry SDKs and send traces, logs, and metrics straight to Hexcovery. Because Hexcovery speaks plain OTLP, there's no Hexcovery-specific SDK to learn or maintain — you use the same instrumentation you'd use with any OpenTelemetry backend.

How it works

Hexcovery exposes an OTLP receiver on gRPC, port :4317, accepting all three standard OTLP services — traces, logs, and metrics. Point your application's OTLP exporter at that endpoint and authenticate with your API key.

OTLP is the protocol, gRPC is the transport

OTLP (OpenTelemetry Protocol) defines the data format; gRPC is how it's carried over the wire. Configure your SDK's OTLP/gRPC exporter (not OTLP/HTTP) and aim it at :4317.

Hexcovery is schema-agnostic on this path: it stores any valid OTLP you send. What gets collected is entirely up to the producer — your app and its instrumentation.

Configure the exporter

Most OpenTelemetry SDKs read these standard environment variables. Set the endpoint and pass your API key as the x-api-key header:

OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.hexcovery.com:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=YOUR_API_KEY

Create the API key in the dashboard — see API keys and Authentication.

Exact endpoint value

Your organization's exact ingest endpoint is shown in the dashboard. Use that value rather than the placeholder above.

Set service identity

Every OTLP producer carries a resource describing what it is. Two attributes matter most for how your data is organized in Hexcovery:

  • service.name — the entity (the piece of software). This becomes a Service in Hexcovery.
  • service.namespace — the Project the entity belongs to. The namespace is the Project boundary.
OTEL_RESOURCE_ATTRIBUTES=service.name=orders-api,service.namespace=superpippo

Read Services and Projects for the full model: an entity exists in its own right, and its service.namespace decides which Project collects it.

Auto-instrumentation

Many languages and frameworks support zero-code auto-instrumentation — you attach an OpenTelemetry agent or import a distro and get traces (and often metrics and logs) for HTTP servers, clients, and database drivers without changing application code. Off-the-shelf SDKs are available for Go, Java, Python, Node.js, .NET, Ruby, PHP, and more.

The general pattern is the same regardless of language:

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.exporter.otlp.endpoint=https://ingest.hexcovery.com:4317 \
  -Dotel.exporter.otlp.protocol=grpc \
  -Dotel.exporter.otlp.headers=x-api-key=YOUR_API_KEY \
  -Dotel.service.name=orders-api \
  -Dotel.resource.attributes=service.namespace=superpippo \
  -jar myapp.jar

OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.hexcovery.com:4317 \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=YOUR_API_KEY \
OTEL_SERVICE_NAME=orders-api \
OTEL_RESOURCE_ATTRIBUTES=service.namespace=superpippo \
opentelemetry-instrument python app.py

OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.hexcovery.com:4317 \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=YOUR_API_KEY \
OTEL_SERVICE_NAME=orders-api \
OTEL_RESOURCE_ATTRIBUTES=service.namespace=superpippo \
node --require @opentelemetry/auto-instrumentations-node/register app.js

Refer to the upstream OpenTelemetry documentation for the exact distro or agent for your language; the Hexcovery-specific parts are only the endpoint and the x-api-key header.

Verify

Once your app is sending data, traces appear on the Traces page and the service shows up in the Services catalog. You can also query directly with OQL:

SELECT count(*) FROM spans WHERE service = 'orders-api' LAST 15m

Next