Install Observe Agent on macOS

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 <YOUR OBSERVE TOKEN> (your instance’s token, such as a1b2c3d4e5f6g7h8i9k0:l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6) and <YOUR OBSERVE COLLECTION ENDPOINT> (your instance’s collection endpoint, such as https://123456789012.collect.observeinc.com/) on each host. For more information on configuring the agent, see Configuration.

Note

The <YOUR OBSERVE COLLECTION ENDPOINT> is composed from https://<OBSERVE_CUSTOMER_ID>.collect.<OBSERVE_INSTANCE>. For example, if you typically login to https://123456789012.observeinc.com, your <YOUR OBSERVE COLLECTION ENDPOINT> is https://123456789012.collect.observeinc.com.

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://raw.githubusercontent.com/observeinc/observe-agent/main/scripts/install_mac.sh" && \
bash install_mac.sh --token=<YOUR OBSERVE 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 OBSERVE 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

self_monitoring:
  enabled: true

host_monitoring:
  enabled: true
  logs: 
    enabled: true
  metrics:
    host: 
      enabled: true
    process:
      enabled: false

# otel_config_overrides:
#   exporters:
#     # This is a net new exporter
#     debug:
#       verbosity: detailed
#       sampling_initial: 5
#       sampling_thereafter: 200
#   service:
#     pipelines:
#       # This will override the existing metrics/host_monitoring pipeline and output to stdout debug instead
#       metrics/host_monitoring_host:
#         receivers: [hostmetrics/host-monitoring-host]
#         processors: [memory_limiter]
#         exporters: [debug]
#       # This is a net new pipeline
#       logs/new-pipeline:
#         receivers: [filelog/host_monitoring]
#         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"

Configure application instrumentation

Once the Observe Agent is up and running on macOS, you can configure your application running on the same macOS to send telemetry data to the Observe Agent using one of the following addresses:

  • OTLP/HTTP endpoint: http://localhost:4318

  • OTLP/gRPC endpoint: http://localhost:4317

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 PowerShell script again. The script will stop the service before installing the new version of the agent and restarting the service.

curl -Ol "https://raw.githubusercontent.com/observeinc/observe-agent/main/scripts/install_mac.sh" && \
bash install_mac.sh