Metrics API

Enterprise DC/OS Preview Updated: April 18, 2017

About the Metrics API

Use the Metrics API to periodically poll for data about your cluster, hosts, containers, and applications. You can then pass this data to a third party service of your choice to achieve informative charts, dashboards, and alerts.

Response format

The API supports JSON only. You will not need to send any JSON, but must indicate Accept: application/json in the HTTP header, as shown below.

Accept: application/json

Host name or IP address

The host name or IP address to use varies according to where your app is running. Private agents will only return metrics to apps running inside of the DC/OS cluster. For this reason, we recommend situating your app inside the cluster so that it can obtain private agent metrics. You might also consider running it as a DC/OS service or job.

  • If your app will run inside of the cluster, use http[s]://localhost[:61001].

  • If your app will run outside of the DC/OS cluster, you should use the cluster URL. In a production environment, this should be the path to the load balancer that sits in front of your masters. To obtain the cluster URL, launch the DC/OS web interface and copy the domain name from the browser. Alternatively, you can log into the DC/OS CLI and type dcos config show core.dcos_url to get the cluster URL. In addition, the DC/OS CLI makes this value available as a variable that you can reference using $(dcos config show core.dcos_url).

Base path

Append /system/v1/metrics/v0/ to the host name, as shown below.


Authentication and authorization

About authentication and authorization

All Metrics API endpoints require an authentication token with one of the following permissions:

  • dcos:superuser
  • dcos:adminrouter:ops:system-metrics

We recommend using dcos:adminrouter:ops:system-metrics for more secure operations.

Obtaining an authentication token

Via the IAM API

To get an authentication token, pass the user name and password of a user with the required permissions in the body of a request to the /auth/login endpoint of the Identity and Access Management Service API. It returns an authentication token as shown below.

  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJib290c3RyYXB1c2VyIiwiZXhwIjoxNDgyNjE1NDU2fQ.j3_31keWvK15shfh_BII7w_10MgAj4ay700Rub5cfNHyIBrWOXbedxdKYZN6ILW9vLt3t5uCAExOOFWJkYcsI0sVFcM1HSV6oIBvJ6UHAmS9XPqfZoGh0PIqXjE0kg0h0V5jjaeX15hk-LQkp7HXSJ-V7d2dXdF6HZy3GgwFmg0Ayhbz3tf9OWMsXgvy_ikqZEKbmPpYO41VaBXCwWPmnP0PryTtwaNHvCJo90ra85vV85C02NEdRHB7sqe4lKH_rnpz980UCmXdJrpO4eTEV7FsWGlFBuF5GAy7_kbAfi_1vY6b3ufSuwiuOKKunMpas9_NfDe7UysfPVHlAxJJgg"

Via the DC/OS CLI

When you log into the DC/OS CLI using dcos auth login, it stores the authentication token value locally. You can reference this value as a variable in curl commands (discussed in the next section).

Alternatively, you can use the following command to get the authentication token value.

$ dcos config show core.dcos_acs_token

Passing an authentication token

Via the HTTP header

Copy the token value and pass it in the Authorization field of the HTTP header, as shown below.

Authorization: token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJib290c3RyYXB1c2VyIiwiZXhwIjoxNDgyNjE1NDU2fQ.j3_31keWvK15shfh_BII7w_10MgAj4ay700Rub5cfNHyIBrWOXbedxdKYZN6ILW9vLt3t5uCAExOOFWJkYcsI0sVFcM1HSV6oIBvJ6UHAmS9XPqfZoGh0PIqXjE0kg0h0V5jjaeX15hk-LQkp7HXSJ-V7d2dXdF6HZy3GgwFmg0Ayhbz3tf9OWMsXgvy_ikqZEKbmPpYO41VaBXCwWPmnP0PryTtwaNHvCJo90ra85vV85C02NEdRHB7sqe4lKH_rnpz980UCmXdJrpO4eTEV7FsWGlFBuF5GAy7_kbAfi_1vY6b3ufSuwiuOKKunMpas9_NfDe7UysfPVHlAxJJgg

Via curl as a string value

Using curl, for example, you would pass this value as follows.

$ curl -H "Authorization: token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJib290c3RyYXB1c2VyIiwiZXhwIjoxNDgyNjE1NDU2fQ.j3_31keWvK15shfh_BII7w_10MgAj4ay700Rub5cfNHyIBrWOXbedxdKYZN6ILW9vLt3t5uCAExOOFWJkYcsI0sVFcM1HSV6oIBvJ6UHAmS9XPqfZoGh0PIqXjE0kg0h0V5jjaeX15hk-LQkp7HXSJ-V7d2dXdF6HZy3GgwFmg0Ayhbz3tf9OWMsXgvy_ikqZEKbmPpYO41VaBXCwWPmnP0PryTtwaNHvCJo90ra85vV85C02NEdRHB7sqe4lKH_rnpz980UCmXdJrpO4eTEV7FsWGlFBuF5GAy7_kbAfi_1vY6b3ufSuwiuOKKunMpas9_NfDe7UysfPVHlAxJJgg"

Via curl as a DC/OS CLI variable

You can then reference this value in your curl commands, as shown below.

$ curl -H "Authorization: token=$(dcos config show core.dcos_acs_token)"

Refreshing the authentication token

Authentication tokens expire after five days by default. If your program needs to run longer than five days, you will need a service account. Please see Provisioning custom services for more information.

API reference

Loading ...


While the API returns informative error messages, you may also find it useful to check the logs of the Metrics service. Refer to Service and Task Logging for instructions.