Install Observe Agent on Windows

Install and Start the Observe Agent

Install the observe-agent package via the provided installation PowerShell script. This script needs to be run in a PowerShell terminal that you run as administrator. Replace YOUR_OBSERVE_TOKEN (your instance’s token, such as a1b2c3d4e5f6g7h8i9k0:l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6) and 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 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 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.

[Net.ServicePointManager]::SecurityProtocol = "Tls, Tls11, Tls12, Ssl3"; Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/observeinc/observe-agent/main/scripts/install.ps1" -outfile .\install.ps1; .\install.ps1 -observe_token "YOUR_OBSERVE_TOKEN" -observe_collection_endpoint "OBSERVE_COLLECTION_ENDPOINT"

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

Get-Service ObserveAgent
Set-Location "${Env:Programfiles}\Observe\observe-agent"
./observe-agent status

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:

observe-agent init-config --token <your token> --observe_url https://<your tenant id>.collect.observeinc.com/

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

Manual configuration

The installation PowerShell script will automatically start the agent for you. You can find the observe-agent.yaml config file in the ${Env:Programfiles}\Observe\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.

Restart-Service ObserveAgent

Configure application instrumentation

Follow these steps to direct your application’s trace data to Observe:

  1. Install the OpenTelemetry App if you have not already done so.

  2. Create a token associated with OpenTelemetry App’s datastream.

  3. Open the agent config file. You can find the observe-agent.yaml config file in the ${Env:Programfiles}\Observe\observe-agent.

  4. Use the otel_config_overrides section to configure an additional OTLP/HTTP Exporter. Replace <YOUR ANOTHER OBSERVE TOKEN> (your instance’s token) and <YOUR OBSERVE COLLECTION ENDPOINT> (your instance’s collection endpoint) on each host.

# this should be added to the existing observe-agent.yaml
otel_config_overrides:
  exporters:
    otlphttp/observe-traces:
      # (ex: https://123456789012.collect.observeinc.com/v2/otel)
      endpoint: "<YOUR OBSERVE COLLECTION ENDPOINT>/v2/otel"
      headers:
        # (ex: Bearer a1b2c3d4e5f6g7h8i9k0:l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6)
        authorization: "Bearer <YOUR ANOTHER OBSERVE TOKEN>"
      sending_queue:
        num_consumers: 4
        queue_size: 100
      retry_on_failure:
        enabled: true
      compression: zstd
  service:
    pipelines:
      traces/forward:
        receivers: [otlp]
        processors: [memory_limiter, resourcedetection, resourcedetection/cloud, batch]
        exporters: [otlphttp/observe-traces]

  1. Restart the Observe Agent

Restart-Service ObserveAgent

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

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

  1. Explore your trace data using the Trace Explorer and the Service Explorer

Uninstall the Observe Agent

Stop-Service ObserveAgent
Remove-Item -Recurse "${Env:Programfiles}\Observe"

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

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.

[Net.ServicePointManager]::SecurityProtocol = "Tls, Tls11, Tls12, Ssl3"; Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/observeinc/observe-agent/main/scripts/install.ps1" -outfile .\install.ps1; .\install.ps1 -observe_token "${OBSERVE_TOKEN}" -observe_collection_endpoint "${OBSERVE_COLLECTION_ENDPOINT}"