Install Observe Agent on Linux¶

Note

These instructions apply to tenants created on or after June 6, 2025. If your tenant was created earlier, follow the legacy guide: Install Observe Agent on Linux [Legacy]. Interested in upgrading to the new experience? Open Docs & Support → Contact Support in the product and let us know.

This page provides instructions for installing the Observe Agent on a Linux system to collect metrics, logs, and application telemetry—including OpenTelemetry traces—and forward them to Observe.

Installation¶

Use the Add Data portal in the product to get the Observe Agent installed in your environment.

Install the Observe Agent¶

Debian-based distributions

Install the observe-agent package. You’ll need to first add the Observe debian repository to your trusted depositories in your sources.list.d file.

echo 'deb [trusted=yes] https://repo.observeinc.com/apt/ /' | sudo tee /etc/apt/sources.list.d/observeinc.list
sudo apt update
sudo apt install observe-agent

To validate that the agent is installed correctly, you can run the version command.

observe-agent version

RedHat-based distributions

Install the observe-agent package. You’ll need to first add the Observe yum repository to your trusted repositories in your yum.repos.d folder.

echo '[fury]
name=Gemfury Private Repo
baseurl=https://yum.fury.io/observeinc/
enabled=1
gpgcheck=0' | sudo tee /etc/yum.repos.d/fury.repo

sudo yum install observe-agent

To validate that the agent is installed correctly, you can run the version command.

observe-agent version

Bash install instructions

Download and install the observe-agent from our official bash script.

curl -OL "https://github.com/observeinc/observe-agent/releases/latest/download/install_linux.sh"
bash install_linux.sh --token=<YOUR_INGEST_TOKEN> --observe_url=<YOUR OBSERVE COLLECTION ENDPOINT> --logs_enabled=true --metrics_enabled=true

This will install the agent locally and initialize the configuration. If your installation uses systemd, the agent will be added as a service and started automatically.

To validate that the agent is installed correctly, you can run the version command.

observe-agent version

Configure the Observe Agent¶

Automatic configuration¶

The easiest way to initialize the agent configuration is to use the observe-agent init-config command as follows:

Replace the contents of the agent configuration file with the config file below. Replace <YOUR_INGEST_TOKEN> with your instance’s ingest token you create from the Add Data for Linux page (ex: a1b2c3d4e5f6g7h8i9k0:l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6) and <YOUR_OBSERVE_COLLECTION_ENDPOINT> with your instance’s collection endpoint (ex: https://123456789012.collect.observeinc.com/) on each host. For more information on configuring the agent, see Configuration.

sudo observe-agent init-config \
--token <YOUR_INGEST_TOKEN> \
--observe_url <YOUR_OBSERVE_COLLECTION_ENDPOINT> \
--forwarding::metrics::output_format=otel \
--self_monitoring::enabled=true \
--host_monitoring::enabled=true \
--host_monitoring::logs::enabled=true \
--host_monitoring::metrics::host::enabled=true \
--host_monitoring::metrics::process::enabled=false

This is only recommended for initial configuration. For subsequent changes, see below.

Manual configuration¶

For initial configuration, we suggest using observe-agent init-config. For changes to the defaults, see below.

Debian-based distributions

Open the agent config file /etc/observe-agent/observe-agent.yaml with superuser permissions which will allow you to edit and save changes to the file.

sudo vim /etc/observe-agent/observe-agent.yaml

Note

Some Observe instances may optionally use a name instead of Customer ID; if this is the case for your instance, contact your Observe Data Engineer to discuss implementation. A stem name will work as is, but a DNS redirect name may require client configuration.

# Observe data token (ex: a1b2c3d4e5f6g7h8i9k0:l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6)
token: "<YOUR_INGEST_TOKEN>"

# Target Observe collection url (ex: https://123456789012.collect.observeinc.com/)
observe_url: "<YOUR_OBSERVE_COLLECTION_ENDPOINT>"

health_check:
    enabled: true
    endpoint: localhost:13133
    path: /status

forwarding:
    enabled: true
    metrics:
        output_format: otel

internal_telemetry:
    enabled: true
    metrics:
        enabled: true
        host: localhost
        port: 8888
        level: detailed
    logs:
        enabled: true
        level: ${env:OTEL_LOG_LEVEL}

self_monitoring:
    enabled: true

host_monitoring:
    enabled: true
    logs:
        enabled: true
        include:
            - /var/log/**/*.log
            - /var/log/syslog
    metrics:
        host:
            enabled: true

# otel_config_overrides:
#   exporters:
#     debug:
#       verbosity: detailed
#       sampling_initial: 5
#       sampling_thereafter: 200
#   service:
#     pipelines:
#       metrics:
#         receivers: [hostmetrics]
#         processors: [memory_limiter]
#         exporters: [debug]

RedHat-based distributions

Open the agent config file /etc/observe-agent/observe-agent.yaml with superuser permissions which will allow you to edit and save changes to the file.

sudo vi /etc/observe-agent/observe-agent.yaml

Note

# Observe data token (ex: a1b2c3d4e5f6g7h8i9k0:l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6)
token: "<YOUR_INGEST_TOKEN>"

# Target Observe collection url (ex: https://123456789012.collect.observeinc.com/)
observe_url: "<YOUR_OBSERVE_COLLECTION_ENDPOINT>"

health_check:
    enabled: true
    endpoint: localhost:13133
    path: /status

forwarding:
    enabled: true
    metrics:
        output_format: otel

internal_telemetry:
    enabled: true
    metrics:
        enabled: true
        host: localhost
        port: 8888
        level: detailed
    logs:
        enabled: true
        level: ${env:OTEL_LOG_LEVEL}

self_monitoring:
    enabled: true

host_monitoring:
    enabled: true
    logs:
        enabled: true
        include:
            - /var/log/**/*.log
            - /var/log/syslog
    metrics:
        host:
            enabled: true

# otel_config_overrides:
#   exporters:
#     debug:
#       verbosity: detailed
#       sampling_initial: 5
#       sampling_thereafter: 200
#   service:
#     pipelines:
#       metrics:
#         receivers: [hostmetrics]
#         processors: [memory_limiter]
#         exporters: [debug]

Start the Observe Agent¶

Now that the configuration is in place, you can start the agent with the following command

sudo systemctl enable --now observe-agent

You can then run the status command to see statistics and information about the agent.

observe-agent status

Configure application instrumentation¶

Once the Observe Agent is deployed, configure your application instrumentation or set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable to one of the following addresses to send application telemetry including traces to the Observe Agent.

Note

When setting up the endpoint to send traces, make sure you use the path that your OTLP library requires. Some libraries need traces to go to /v1/traces, while others expect them at the root path /.

OTLP/HTTP endpoint: http://localhost:4318
OTLP/grpc endpoint: http://localhost:4317

Learn more about how to instrument your app

Uninstall the Observe Agent¶

Debian-based distributions

You can uninstall the agent via apt after stopping the service.

sudo systemctl stop observe-agent
sudo apt-get purge observe-agent

RedHat-based distributions

You can uninstall the agent via yum after stopping the service.

sudo systemctl stop observe-agent
sudo yum erase observe-agent -y

Upgrade the Observe Agent¶

Warning

Observe Agent v2.0.0 includes breaking changes. Learn more about these changes in Upgrade to Observe Agent v2.0.0 Observe Agent v1.0.0 includes breaking changes. Learn more about these changes in Upgrade to Observe Agent v1.0.0

Debian-based distributions

Upgrade the package version. The install process will ask if you want to replace your existing config file. Generally the default answer of N (no) is correct.

sudo apt update
sudo apt install --only-upgrade observe-agent

To apply the new configs and start the agent at the new version you can run the following command.

sudo systemctl restart observe-agent

RedHat-based distributions

Upgrade the package version. The install process will ask if you want to replace your existing config file. Generally the default answer of N (no) is correct.

sudo yum update observe-agent
sudo yum install observe-agent

To apply the new configs and start the agent at the new version you can run the following command.

sudo systemctl restart observe-agent

Next steps¶

Use both the Log Explorer and the Metric Explorer to monitor your systems. To analyze your trace data, explore both the Trace Explorer and the Service Explorer