The Observe Agent runs on your hosts and in your infrastructure. It collects logs, metrics, traces, and Kubernetes events, and sends them to Observe by Snowflake. The Observe Agent is a distribution of the OpenTelemetry Collector with Observe defaults for host monitoring, Kubernetes collection, and the Observe by Snowflake ingest endpoint.

What is the Observe Agent?

On a host, the Observe Agent is one process. It reads host metrics and the log files you configure, and it accepts application telemetry on the local machine. It then sends that data over HTTPS to your Observe by Snowflake collection endpoint.

In Kubernetes, you install the Observe Agent with the Observe Helm chart. The chart runs several workloads: a DaemonSet on each node for logs and metrics, single-instance deployments for cluster events and cluster metrics, a Prometheus scraper, a forwarder DaemonSet that accepts OTLP, and a monitor that scrapes the agents themselves. See Helm Chart components.

The Observe Agent pushes data. It authenticates with a Datastream ingest token. You must provide the following settings:

• token: the ingest token from the Add Data portal. This token is for ingest only. It is separate from an Observe by Snowflake API token.
• observe_url: your collection endpoint, such as https://<customer-id>.collect.observeinc.com/.

On Linux, both settings live in /etc/observe-agent/observe-agent.yaml. The Observe Agent reads that file at startup and generates an OpenTelemetry Collector configuration from it. See Configure the Observe Agent on Linux, Windows, and macOS.

If you already run an OpenTelemetry Collector, you can export to the same collection endpoint and skip the Observe Agent. The agent is the packaged collector plus Observe host and Kubernetes defaults.

After data arrives, host telemetry shows up in Host Explorer, Kubernetes telemetry in Kubernetes Explorer, and application traces in Trace Explorer.

When should I use the Observe Agent?

Use the Observe Agent when:

• You want system logs and host metrics in Observe by Snowflake with a single package.
• You want one collector configuration for bare metal, virtual machines, and Kubernetes.
• Your applications already emit OTLP, and you want a local receiver on each host or node that forwards to Observe by Snowflake.

For logs that already land in Amazon S3, use FileDrop. For cloud APIs that Observe polls, use a poller or the Add Data app for that provider. For Snowflake account telemetry, use the Observe for Snowflake native app.

Where do I get the Observe Agent?

The Observe Agent source, releases, and changelog are available on GitHub.

Container images:

• Docker Hub: observeinc/observe-agent
• Amazon ECR Public: public.ecr.aws/observeinc/observe-agent

The Kubernetes install uses the Observe Helm chart. Helm Chart releases are separate from Observe by Snowflake platform releases. See Helm chart.

Where can I install the Observe Agent?

The Observe Agent builds for x86_64 and arm64. You can install it on hosts, in containers, and in on-premises data centers.

Local devices

See Install on a host.

A host install runs as a system service (systemd on Linux). It reads the log paths in host_monitoring.logs.include. Host metrics are on by default. Process metrics stay off until you set host_monitoring.metrics.process.enabled to true.

Kubernetes

Install the agent with the Observe Helm chart, usually from Data & integrations > Add Data > Kubernetes. See Install on Kubernetes.

Keep cluster-events, cluster-metrics, prometheus-scraper, and monitor at one replica each. A second replica duplicates cluster data.

Amazon ECS

You can run the Observe Agent on Amazon ECS with EC2 or Fargate. See Install on Amazon ECS.

Docker

Run the published image when you want the Observe Agent as a container on a host that is not Kubernetes. See Install Docker image.

Ansible

Ansible is an install method for Linux and Windows hosts, not a separate runtime. See Install on Ansible.

What the agent collects

Spans longer than forwarding.traces.max_span_duration (default 1h) are dropped.

Network

The Observe Agent needs outbound HTTPS to your collection endpoint. No inbound port has to be reachable from outside the host.

The following listeners bind to localhost:

Leave these ports unpublished. In Docker, the metrics endpoint binds to 0.0.0.0 so other containers can scrape it. Do not map port 8888 onto the host network.

Use the following command to check if the Observe Agent is running:

observe-agent status

Disk usage and buffering

Disk usage depends on the installation method, agent logs, and whether you configure persistent exporter queues.

The Observe Agent uses OpenTelemetry Collector components. By default, plan for space for the installed package and the agent's own logs. If you configure an exporter with a persistent sending_queue, also plan for queue data written by the OpenTelemetry Collector file_storage extension. Queue size depends on your configuration, telemetry volume, event size, and the length of an outage between the agent and the Observe collection endpoint.

Configure additional Collector components under otel_config_overrides in observe-agent.yaml. See Configure the Observe Agent on Linux, Windows, and macOS.

CPU and memory usage

CPU and memory usage depend on:

• The volume and size of logs, metrics, and traces.
• The number of files, containers, processes, and Prometheus targets the agent monitors.
• Parsing, multiline detection, filtering, transformation, sampling, and other processors.
• Metric cardinality.
• Exporter batching, retries, and queued data when the Observe endpoint is unavailable.
• Any custom pipelines under otel_config_overrides.

Monitor the Observe Agent's resource use in your environment before setting production limits. The Observe Agent exposes its own Prometheus metrics on port 8888. You can also enable self_monitoring to send agent telemetry to Observe by Snowflake.

Hosts

A host installation runs one Observe Agent process. Start with host metrics and only the log paths you need. Process metrics are disabled by default because collecting per-process data increases CPU and memory use.

Add custom receivers and processors one at a time, then measure their effect.

Kubernetes

The Helm chart creates several workloads with separate resource requests and limits. The node-logs-metrics DaemonSet runs on every selected node; cluster-level collectors and the monitor run as separate deployments.

Use the resource values in the version of the Helm chart you install as your starting point. Adjust them after reviewing actual CPU usage, memory usage, throttling, restarts, dropped telemetry, and queue growth.
See Helm chart and the chart's values.yaml for current defaults.