Use the Telemetry API

This document describes how to configure the Ops Agent to use the Telemetry (OTLP) API, telemetry.googleapis.com. The Telemetry API is an implementation of the open-source OpenTelemetry Line Protocol. When you enable this feature, the Ops Agent sends both logs and metrics to your Google Cloud project by using the Telemetry API rather than the proprietary Cloud Monitoring API and Cloud Logging API.

If you adopt the use of the Telemetry API in the Ops Agent and have charts or alerting policies that monitor your API usage, then you must update these artifacts to monitor the telemetry.googleapis.com endpoint rather than the monitoring.googleapis.com or logging.googleapis.com endpoints.

Before you begin

To use the Telemetry API, do the following:

  1. Enable the Telemetry API in your Google Cloud project, if it is not already enabled. You can enable the API by running the following command:

    gcloud services enable telemetry.googleapis.com

  2. Adjust Telemetry API quotas, if the default values are not sufficient. The Telemetry API has quotas separate from those of the Cloud Monitoring API and Cloud Logging API. For information about the quotas and limits for the Telemetry API, see the following:

    You might need to adjust these quotas to accommodate the volume of telemetry data you ingest.

Configure the Ops Agent to use the Telemetry API

During the Preview period, use of the Telemetry API by the Ops Agent is controlled by an environment variable, EXPERIMENTAL_FEATURES. To collect telemetry by using the Ops Agent and the Telemetry API, you must do the following, as described in the following sections:

  1. Install a version of the Ops Agent that supports the Telemetry API.
  2. Set the EXPERIMENTAL_FEATURES environment variable.
  3. Restart the Ops Agent to pick up the change.

Use Ops Agent version 2.66.0 or newer

To use the Telemetry API with the Ops Agent, you must install the Ops Agent version 2.66.0 or newer. For information about installing the Ops Agent, see Install the Ops Agent of individual VMs.

Set the environment variable

Give the Ops Agent access to the Telemetry API by setting the EXPERIMENTAL_FEATURES environment variable to the value otlp_exporter, as shown in the following tabs:

Linux

To modify the environment for the Ops Agent, run the following commands on your instance:

for service in \
        google-cloud-ops-agent \
        google-cloud-ops-agent-fluent-bit \
        google-cloud-ops-agent-opentelemetry-collector \
        ; do
        sudo mkdir -p "/etc/systemd/system/${service}.service.d"
        echo -e '[Service]\nEnvironment="EXPERIMENTAL_FEATURES=otlp_exporter"' | sudo tee "/etc/systemd/system/${service}.service.d/otlp_exporter.conf"
done
sudo systemctl daemon-reload

Windows

To modify the environment for the Ops Agent, perform the following steps:

  1. Connect to your instance using RDP or a similar tool and login to Windows.
  2. Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator
  3. Set the EXPERIMENTAL_FEATURES environment variable by running the following PowerShell command: 
    setx EXPERIMENTAL_FEATURES "otlp_exporter" /M

Restart the Ops Agent

Linux

  1. To restart the agent, run the following command on your instance: 
    sudo systemctl restart google-cloud-ops-agent
  2. To confirm that the agent restarted, run the following command and verify that the components "Metrics Agent" and "Logging Agent" started: 
    sudo systemctl status "google-cloud-ops-agent*"

Windows

  1. Connect to your instance using RDP or a similar tool and login to Windows.
  2. Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator
  3. To restart the agent, run the following PowerShell command: 
    Restart-Service google-cloud-ops-agent -Force
  4. To confirm that the agent restarted, run the following command and verify that the components "Metrics Agent" and "Logging Agent" started: 
    Get-Service google-cloud-ops-agent*

Configure the Ops Agent to not use the Telemetry API

To stop the Ops Agent from collecting telemetry by using the Telemetry API and to resume collecting telemetry by using the Cloud Monitoring API and the Cloud Logging API, you must do the following:

  1. Unset the EXPERIMENTAL_FEATURES environment variable.

    Linux

    To modify the environment for the Ops Agent, run the following commands on your instance:

    sudo find /etc/systemd/system -name otlp_exporter.conf | sudo xargs rm
sudo systemctl daemon-reload

    Windows

    To modify the environment for the Ops Agent, perform the following steps:

    1. Connect to your instance using RDP or a similar tool and login to Windows.
    2. Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting Run as Administrator
    3. Remove the EXPERIMENTAL_FEATURES environment variable by running the following PowerShell command: 
      REG delete "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /F /V EXPERIMENTAL_FEATURES

  2. Restart the Ops Agent to pick up the change.

What's next