Skip to content

Quick Start

Get telemetry into Hexcovery and see it in the dashboard in about five minutes. You'll create an API key, send some data — either from a server or from an application — and open the dashboard to confirm it arrived.

Before you start

You need a Hexcovery organization and an admin account to create an API key. Your organization owns all of its data, users, and billing. If you don't have one yet, sign up first.

1. Create an API key

API keys are scoped to your organization and used by the agent, OpenTelemetry exporters, and any automation that ingests or queries data.

  1. Sign in to the dashboard and open Organization settings (admin only).
  2. Create a new API key and copy it somewhere safe — it identifies your organization on every request.

Keep the key out of source control. Provide it through an environment variable instead:

export HEXCOVERY_API_KEY="<your-api-key>"

The key is passed as the x-api-key header on ingest and as X-API-Key when you query the API.

2. Send data

Pick one path to start. You can add the other later — most setups eventually use both.

The agent collects system metrics (CPU, memory, disk, network, processes) and host logs from a Linux server, and Kubernetes metrics from a cluster.

On a Linux host, install the binary as a systemd service and point it at the ingest endpoint with your API key:

sudo cp hexcovery-agent /usr/local/bin/
sudo cp hexcovery-agent.service /etc/systemd/system/
sudo systemctl enable --now hexcovery-agent

Configure the server endpoint and API key (via /etc/hexcovery-agent/config.yaml or the HEXCOVERY_SERVER_ENDPOINT / HEXCOVERY_API_KEY environment variables).

Within a minute or two the host shows up on the Hosts page.

Full instructions, configuration, and the Kubernetes (Helm) install: Install the agent on Linux.

Instrument your application with a standard OpenTelemetry SDK and export over OTLP gRPC to Hexcovery's ingest endpoint on port 4317, with your API key in the x-api-key header.

A typical OTLP exporter configuration:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-ingest-endpoint>:4317"
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=$HEXCOVERY_API_KEY"
export OTEL_SERVICE_NAME="checkout"
export OTEL_RESOURCE_ATTRIBUTES="service.namespace=shop"

service.name names the service; service.namespace groups it into a Project (see Services and Projects). Traces, logs, and metrics all arrive over the same OTLP endpoint.

Full instructions and per-language examples: Send data with OpenTelemetry.

3. See it in the dashboard

Open the dashboard and check the built-in page for what you sent:

  • Installed the agent → Hosts (and Kubernetes for a cluster).
  • Sent OTLP → Services, Traces, and Logs.

No data yet? Give it a minute, confirm the API key is correct, and check that the endpoint and port are reachable from where your agent or app runs.

4. Query it with OQL

In the dashboard's Explorer, run a query against your new data with OQL:

SELECT avg(cpu_user_pct) FROM host LAST 1h

The Explorer auto-selects a chart from the query shape. You can save the query, add it to a dashboard, or share it.

Next steps

  • Core Concepts — entities, signals, services, and Projects.
  • Sending Data — every ingest option in detail.
  • OQL — the full query language.
  • Alerting — turn a query into a rule and get notified.