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

Create an ingest token

Create an ingest token in the Add Data portal, and be sure to record this token in a safe place, as you will need to provide it during the installation.

1. From the left navigation, click Data & integrations > Add Data.
2. Click Windows.
3. Click Create to generate a new ingest token.

Install and start the Observe Agent

Run the following bash script to download the observe-agent binary and start the Observe Agent launch daemon. This script needs to be run in a terminal, and you will need to enter your password to run the script as administrator.

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 MacOS page (ex: a1b2c3d4e5f6g7h8i9k0:l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6) and <YOUR_OBSERVE_COLLECTION_ENDPOINT> with your instance’s collection endpoint (ex: https://123456789012.collect.observeinc.com/). For more information on configuring the agent, see Configuration.

📘

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.

curl -OL "https://github.com/observeinc/observe-agent/releases/latest/download/install_mac.sh" && \
bash install_mac.sh --token=<YOUR_INGEST_TOKEN> --observe_url=<YOUR_OBSERVE_COLLECTION_ENDPOINT> --logs_enabled=true --metrics_enabled=true

To validate that the agent is installed correctly, you can run the following commands.

observe-agent version

Configure the Observe Agent

The installation bash script will automatically start the agent for you. You can find the observe-agent.yaml config file in the /usr/local/observe-agent directory. For more information on configuring the agent, see 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>"

# Debug mode - Sets agent log level to debug
debug: false

# Enable forwarding of local app metrics and traces
forwarding:
    enabled: true
    metrics:
        output_format: otel

# collect metrics and logs pertaining to the agent itself
self_monitoring:
  enabled: true

# collect metrics and logs about the host system
host_monitoring:
    enabled: true
    logs:
        enabled: true
    metrics:
        # collect metrics about the host system
        host:
            enabled: true
        # collect metrics about the processes running on the host system
        process:
            enabled: false

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

Restart the Observe Agent with the updated configuration

If you made any configuration updates, you can restart the agent and apply the new config with the following command.

sudo launchctl stop "com.observeinc.agent"

Send application data to Observe

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

See APM instrumentation for more information about how to instrument your app for observability.

Uninstall the Observe Agent

Run the following commands to uninstall the Observe Agent:

sudo launchctl stop "com.observeinc.agent"
sudo launchctl unload -wF /Library/LaunchDaemons/com.observeinc.agent.plist
sudo rm -rf /usr/local/bin/observe-agent /usr/local/libexec/observe-agent /usr/local/observe-agent /Library/LaunchDaemons/com.observeinc.agent.plist

Upgrade the Observe Agent

To upgrade the Observe Agent, run the installation script again. The script stops the service before installing the new version of the agent, then restarts the service.

curl -OL "https://github.com/observeinc/observe-agent/releases/latest/download/install_mac.sh" && \
bash install_mac.sh