For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

You can explore available metrics, compare metric data, and create charts for your dashboards.

Enable Insights During Resource Creation

After you opt in to the public preview, you can enable the available Insights telemetry from the resource creation page when you create a supported DigitalOcean resource. For Droplets and GPU Droplets, select Install the Observability agent to install the agent during resource creation.

For supported managed resources that do not require the Observability agent, the resource creation page displays the available logs and traces options directly. When creating Managed Agents resources, Insights is enabled by default.

Explore Metrics Using the Control Panel

The Explore tab displays all available metrics for the selected region. The left panel lists the available metrics, and the main area displays charts for the metrics you select, allowing you to browse and compare metric data.

To explore metrics, go to the DigitalOcean Control Panel, in the left menu, click DATA & LEARNING, click Insights, and then click the Metrics tab.

Set the Region

At the top of the Metrics tab, click the Region dropdown menu to select the region whose metrics you want to view.

Set the Time Range and Refresh Interval

The time range, timezone, and refresh interval apply to both the Explore and Query tabs.

Set the Time Range

To set the time range, in the top-right corner, click the Time range dropdown menu to select a relative range from Last 5 minutes through Last 7 days, or specify an absolute From and To range.

Use the Timezone field to select the timezone used to display metric timestamps. The default is your local browser timezone.

Set the Refresh Interval

To set the refresh interval, in the top-right corner, click the Refresh interval dropdown menu to select Off, 15 sec, 30 sec, or 60 sec.

Click the refresh icon to refresh the metric data immediately.

Select Metrics

You can select multiple metrics to compare their data. Each selected metric appears as a separate chart. By default, no metrics are selected, and the explorer displays all available metrics.

To select specific metrics, use the Metrics panel on the left. Search for a metric using the Search metrics field, select an entire metric group, or expand a group, such as do.droplets, and select individual metrics.

To remove a metric from your selection, clear its checkbox.

Filter Metrics

To limit the metric data displayed, click + Filter, and then configure the filter:

• In the Label field, select or enter the label to filter by. For example, use resource.urn to filter metrics for a specific resource.
• Click the Operator dropdown menu, and then select the comparison operator.
• In the Value field, select or enter the value to compare against.

Then, click Apply to apply the filter.

Explore Metrics Using Automation

To list the label names available for metric series in a region, send a request to the List Metric Label Names endpoint:

curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/labels"

To list the available values for a specific metric label, send the label name to the List Metric Label Values endpoint:

curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/label/__name__/values"

To find metric series that match one or more label selectors, send a request to the Find Metric Series endpoint:

curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  --get "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/series" \
  --data-urlencode 'match[]={__name__="do.droplets.cpu_time"}'

Add a Metric to a Dashboard Using the Control Panel

Use the Query tab to build and customize a chart that you can save to a dashboard.

To add a metric to a dashboard, go to the Control Panel, in the left menu, click DATA & LEARNING, click Insights, click the Metrics tab, and then click the Query tab.

The Query tab uses the same chart and query configuration options available when adding a chart to a dashboard. Configure the chart type, query, visualization options, and other chart settings.

After configuring the chart, click Save to Dashboard in the top-right corner to open the Save to Dashboard window.

In the Destination section, you can either select an Existing dashboard or create a New dashboard.

Add Metric to Existing Dashboard

If you choose to use an existing dashboard, click the Dashboard dropdown menu, and then select the dashboard where you want to add the chart.

Then, click the Group dropdown menu, and then select the group where you want the chart to appear.

In the Chart title field, enter a descriptive title for the chart.

Then, click Save to Dashboard.

Add Metric to New Dashboard

If you choose to create a new dashboard, in the Dashboard name field, enter a name for the dashboard.

In the Panel Title field, enter a title for the chart.

Then, click Save to Dashboard. The new dashboard appears in the Dashboards tab.

Query Metrics Using Automation

To retrieve metric data for a single point in time, send a PromQL query to the Execute an Instant PromQL Query endpoint:

curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  --get "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/query" \
  --data-urlencode "query=do.droplets.cpu_time"

To retrieve metric data over a time range, send a PromQL query to the Execute a Range PromQL Query endpoint:

curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  --get "https://api.digitalocean.com/v2/insights/query/nyc3/prom/api/v1/query_range" \
  --data-urlencode "query=do.droplets.cpu_time" \
  --data-urlencode "start=1620683817" \
  --data-urlencode "end=1620705417" \
  --data-urlencode "step=15s"