OpenTelemetry

Send your sandboxes' metrics and events to Datadog, Grafana Cloud, Honeycomb or any OTLP collector.

agental sends what happens to your sandboxes to one OTLP/HTTP collector that you choose. Nothing is installed in the sandboxes.

Set the collector#

curl -X PUT https://agental.io/v1/telemetry \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endpoint":"https://otlp.datadoghq.com","headers":{"dd-api-key":"<DATADOG_API_KEY>"}}'

• endpoint is the collector's base address. /v1/metrics and /v1/logs are added to it, and one you paste with either on the end is taken off.
• It has to be https://, on port 443 or 4318, on the public internet. Redirects are not followed.
• headers are sent with every export: what your collector checks, such as its API key. At most 20. Their values are kept and never shown again, not even to you.
• An account has one collector. Setting it again replaces it.
• Setting it sends nothing. The first metrics go at the next whole minute, and nothing from before it was set is sent.

Test it#

curl -X POST https://agental.io/v1/telemetry/test \
  -H "Authorization: Bearer $AGENTAL_API_KEY"

Sends one empty metrics export with your headers, and answers with what the collector said: ok, its HTTP status, and a message when something is wrong. A wrong key or address shows here, not after a minute of waiting. In the CLI, agental telemetry set <endpoint> -H name=value sets it and tests it.

Vendor settings#

Metrics#

• All are gauges.
• Every point of a sandbox has agental.sandbox.id and agental.sandbox.name, so each sandbox is its own series.
• A sandbox sends points only while it runs. Each export holds the minutes since the last one the collector took.

There is no figure for time stalled on disk. The host does not measure it for a virtual machine, and the CPU's own iowait is not the same thing, so it is not sent in its place.

Events#

Each sandbox event is one log record. Its name is in the record's eventName and in its event.name attribute, and its body is the webhook's body, word for word.

sandbox.error is sent with the severity ERROR, and every other event with INFO.

Delivery and errors#

• Metrics are sent in time order.
• After an outage, the metrics of the last 10 minutes that the collector missed are sent, and no older. They are read again from where they are kept, not held for you meanwhile.
• Events the collector missed are sent again, from the last 24 hours at most.

Read and remove#

curl -X GET https://agental.io/v1/telemetry \
  -H "Authorization: Bearer $AGENTAL_API_KEY"

The answer's telemetry is null when none is set. Otherwise it has the endpoint, the names of its headers, lastExportAt, when the collector last took the metrics, and lastError, the last thing that went wrong with the metrics or the events.

curl -X DELETE https://agental.io/v1/telemetry \
  -H "Authorization: Bearer $AGENTAL_API_KEY"

Nothing more is sent to the collector, and its headers are forgotten.

In the console#

Settings has an OpenTelemetry export section: set the collector, send a test, and see the last export and the last error.

Errors#

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]