Honeycomb

Observability

Synopsis

Creates a Honeycomb target that sends logs, metrics and traces to Honeycomb over OTLP.

The target is the OTLP target with Honeycomb's sign-in and dataset built in.

Schema

- name: <string>
  description: <string>
  type: honeycomb
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    url: <string>
    api_key: <string>
    dataset: <string>
    send_metrics: <boolean>
    cumulative_to_delta: <boolean>
    compression: <boolean>
    timeout: <numeric>
    batch_size: <numeric>
    max_retries: <numeric>
    retry_delay: <numeric>
    disable_retries: <boolean>
    debug:
      status: <boolean>
      dont_send_logs: <boolean>

Configuration

The following fields are used to define the target:

Field	Required	Default	Description
name	Y		Target name
description	N	-	Optional description
type	Y		Must be honeycomb
pipelines	N	-	Optional post-processor pipelines
status	N	true	Enable/disable the target

Connection

Field	Required	Default	Description
url	Y	-	Honeycomb's OTLP endpoint: https://api.honeycomb.io (US) or https://api.eu1.honeycomb.io (EU). It must use https. In the console: OTLP endpoint
api_key	Y	-	An ingest API key of the Honeycomb environment that receives the data. It can be plain text, an environment variable or a secret. In the console: API key
dataset	Y	-	The dataset that every request names. See Datasets. In the console: Dataset
send_metrics	N	true	Sends the readings of metric devices as metrics. false sends them as log records. In the console: Readings as metrics
cumulative_to_delta	N	false	true sends counters as deltas, as described in the OTLP page's Counters as deltas section. YAML only

Performance

Field	Required	Default	Description
compression	N	true	Compresses each request with gzip. YAML only
timeout	N	30	How long a request may take, in seconds
batch_size	N	1000	The most events sent in one request
max_retries	N	3	How many times a failed request is retried
retry_delay	N	1	How long to wait before a retry, in seconds
disable_retries	N	false	true sends each batch once, as on the OTLP page. In the console: Disable retries

Scheduling

See Scheduling and Pool Behavior for interval and cron fields shared by all targets.

Debug Options

The debug options work as on the OTLP page.

Settings That Do Not Apply

The target always sends OTLP over HTTP with protobuf, and it checks Honeycomb's certificate against the system's trust store. So it ignores protocol, format, path, grpc_passthrough, address, port and tls.

It signs in itself, so it replaces the x-honeycomb-team and x-honeycomb-dataset headers if they are set under headers.

The Console Form

The form has one step, Honeycomb settings:

• OTLP endpoint;
• API key, with the Manual / Environment variable / Vault picker;
• Dataset;
• Readings as metrics, on by default;
• the Performance fields.

Details

Where to Find the Values

In Honeycomb, open the environment's settings and create an ingest API key on its API keys tab. EU teams use the EU endpoint.

How the Target Signs In

The target sends the API key in the x-honeycomb-team header, and the dataset in the x-honeycomb-dataset header, of every request.

Datasets

• In Honeycomb Environments, metrics go to the dataset that the target names. Traces go to a dataset named after their service.name. For a device's records, service.name is the device's name.
• Honeycomb Classic puts all data in the dataset that the target names.

Counters

By default, the target sends counters unchanged. Set cumulative_to_delta to true to send them as deltas, as described in the OTLP page's Counters as deltas section.

Size

Honeycomb documents no limit for an OTLP request, so the target keeps the OTLP target's own behavior.

Everything else works as on the OTLP page.

Examples

A US Team

A US team, with the API key from a secret...

targets: - name: honeycomb type: honeycomb properties: url: "https://api.honeycomb.io" api_key: "$secret{honeycomb-ingest-key}" dataset: "metrics"

An EU Team

An EU team, with the API key from an environment variable...

targets: - name: honeycomb_eu type: honeycomb properties: url: "https://api.eu1.honeycomb.io" api_key: "${HONEYCOMB_API_KEY}" dataset: "plant-metrics"

Troubleshooting

Configuration Errors

Director refuses a configuration it cannot use, with one of these messages:

• url is required for Honeycomb
• url for Honeycomb must be the https OTLP endpoint, such as https://api.honeycomb.io
• api_key is required for Honeycomb
• dataset is required for Honeycomb
• the api_key of the Honeycomb target resolved to nothing: check the environment variable or the secret it names: api_key is set, but its environment variable or secret is empty.
• failed to resolve the api_key of the Honeycomb target: ...: the environment variable or the secret could not be read.

Errors from Honeycomb

The OTLP page's Troubleshooting entries apply. For Honeycomb in particular:

• status 401: the API key is wrong, or it belongs to another environment or region.
• status 429: the team is over a Honeycomb rate limit. The target retries.
• Metrics in a dataset named unknown_metrics: the data did not name a dataset. This target always names one, so check the dataset in the target's settings.