Metrics
Export Metrics on your APIs with Traefik Hub & Open Telemetry
Introduction
Traefik Hub uses OpenTelemetry (sometimes referred to as OTel).
Open Telemetry is an open-source observability framework that allows you to collect, process, and export telemetry data from applications and infrastructure.
Open Telemetry helps you get insights into system performance and behavior.
At any point while reading this documentation you need additional information on OpenTelemetry, you can refer to its official documentation.
Configuration
To enable OpenTelemetry, you have to adjust the default configuration of your Traefik Hub agent by adding the following values.
Values
| Value | Description | Required |
|---|---|---|
hub.metrics.opentelemetry.insecure | Setting it to true allows Prometheus to connect to the OpenTelemetry endpoint hub.metrics.opentelemetry.address. | Yes |
hub.metrics.opentelemetry.address | The address of your Prometheus instance. This can be an internal (prometheus.monitoring:9090) or external (monitoring.example.com) URL. | Yes |
hub.metrics.opentelemetry.path | The OpenTelemetry endpoint used by the Traefik Hub agent. The default endpoint is /api/v1/otlp/v1/metrics. | Yes |
Adjust the Configuration
If you don't have it already, save the default Traefik Hub configuration using Helm.
helm show values traefik/traefik-hub > values.yaml
Second, adjust the values.yaml file by adding the configuration for OpenTelemetry to the additionalArguments part of the file.
additionalArguments:
- --hub.metrics.opentelemetry.insecure=true
- --hub.metrics.opentelemetry.address=prometheus.monitoring:9090
- --hub.metrics.opentelemetry.path=/api/v1/otlp/v1/metrics
In the shown example above, hub.metrics.opentelemetry.address points to an internal running Prometheus cluster (prometheus.monitoring:9090).
For more information, please read the documentation about the configuration options.
Deploy Your Custom Settings
Once the configuration is adjusted, use Helm to (re)deploy the Traefik Hub agent with the new values to enable OpenTelemetry.
helm upgrade --install --namespace traefik-hub traefik-hub traefik/traefik-hub \
--values values.yaml
Congratulations, OpenTelemtry is now enabled.
If you prefer, you can also deploy the needed additionalArguments to enable OpenTelemetry as a "one-liner" command with Helm.
You can do that by adding the additionalArguments values through --set.
helm upgrade --install --namespace traefik-hub traefik-hub traefik/traefik-hub --set additionalArguments='{\
--hub.metrics.opentelemetry.insecure,\
--hub.metrics.opentelemetry.address=prometheus.monitoring:9090,\
--hub.metrics.opentelemetry.path=/api/v1/otlp/v1/metrics\
}'
Please refer to the official Helm documentation to learn more about --set and the use of arrays and list.
Metrics
Metrics are used to measure and record quantitative data about the performance and behavior of your APIs.
Metrics are aggregated over time, allowing you to understand trends and patterns.
Traefik Hub exposes different kinds of metrics:
Metrics do not provide detailed information about individual requests or transactions.
Metrics provide aggregated information about the overall system or application.
Dataflow Metrics
| Metric | Type | Description |
|---|---|---|
traefik_hub_api_requests_total | Counter | The number of handled API requests. |
traefik_hub_api_requests_duration_milliseconds_sum traefik_hub_api_requests_duration_milliseconds_count traefik_hub_api_requests_duration_milliseconds_bucket | Histogram | Processing duration histograms. |
traefik_hub_api_requests_bytes_total | Counter | Requests size (in bytes) handled by APIs (body size). |
traefik_hub_api_responses_bytes_total | Counter | Responses size (in bytes) handled by APIs (body size). |
code, method, protocol, user_id, email, token_name, api_name, api_version_name, api_namespace, gateway_name, agent_id, instance_id, tls_version, tls_cipher
API Management Metrics
| Metric | Type | Labels | Description |
|---|---|---|---|
traefik_hub_api_gateways_ratio | Gauge | agent_id, instance_id | Number of API Gateways. |
traefik_hub_apis_ratio | Gauge | agent_id, instance_id, api_namespace | Number of APIs. |
traefik_hub_api_gateway_apis_ratio | Gauge | agent_id, instance_id, gateway_name | Number of APIs published on API Gateways. |
traefik_hub_api_portal_apis_ratio | Gauge | agent_id, instance_id, portal_name | Number of APIs published on API Portals. |
traefik_hub_api_versions_ratio | Gauge | agent_id, instance_id, api_name, api_namespace | Number of API versions. |
traefik_hub_api_collections_ratio | Gauge | agent_id, instance_id, api_namespace | Number of API collections. |
traefik_hub_api_rate_limits_ratio | Gauge | agent_id, instance_id | Number of API Rate Limit. |
traefik_hub_api_accesses_ratio | Gauge | agent_id, instance_id | Number of API Accesses. |
traefik_hub_api_keys_ratio | Gauge | agent_id, instance_id, user_id, user_email | Number of API keys with access to APIs on the agent. |
traefik_hub_users_ratio | Gauge | agent_id, instance_id | Number of users that belong to a group attached to at least one API Access. |
traefik_hub_user_groups_ratio | Gauge | agent_id, instance_id | Number of groups attached to at least one API Access. |
traefik_hub_portals_ratio | Gauge | agent_id, instance_id, portal_type | Number of API Portals. |
Ingress Metrics
| Metric | Type | Description |
|---|---|---|
traefik_hub_edge_ingresses_ratio | Gauge | Number of edge ingress deprecated. |
traefik_hub_ingresses_ratio | Gauge | Number of Ingresses in the cluster. |
traefik_hub_ingress_routes_ratio | Gauge | Number of Traefik Ingresses in the cluster. |
traefik_hub_services_ratio | Gauge | Number of Services in the cluster. |
traefik_hub_acps_ratio | Gauge | Number of ACPs deprecated. |
agent_id, instance_id
Deployment Metrics
| Metric | Type | Labels | Description |
|---|---|---|---|
traefik_hub_api_nodes_ratio | Gauge | agent_id, instance_id | Number of nodes hosting microservices serving APIs. |
traefik_hub_nodes_ratio | Gauge | agent_id, instance_id | Number of nodes in the cluster. |
Labels
Labels, also known as tags or dimensions, are key-value pairs that provide context to metrics.
Labels add additional information to your metrics and traces, allowing you to segment and filter data to gain more insights.
| Label | Description | Example |
|---|---|---|
code | Request code | "200" |
method | Request Method | "GET" |
protocol | Request protocol | "http", "grpc", ... |
user_id | Unique user identifier | "645133c75d2aee16b07ef3da" The user_id holds the internal ID or the JWT ID, depending on where the user comes from. |
email | User email | "[email protected]" The owner of the API Key or Application consuming the API. |
token_name | Name of the API key used to authenticate. | "my-test-token" |
api_name | Name of the API. | "flight-api" |
api_version_name | The version of the API. | "flight-api-v2" |
api_namespace | Namespace of the API. | "airlines" |
gateway_name | Name of the API Gateway. | "my-gateway" |
agend_id | Identifier of the Traefik Hub agent. | "5d351900-26e0-408a-8f36-2112b50b26ff" |
instance_id | Pod ID of the Traefik Hub agent instance. | "traefik-6d67f77db9-nrrnm" |
tls_version | TLS version used for the request. | "1.0" |
tls_cipher | TLS cipher used for the request. | "TLS_FALLBACK_SCSV" |
portal_type | Type of the API Portal. | "single_cluster", "multi_cluster" |
portal_name | Name of the API Portal. | "my-api-portal" |
Related Content
- Learn how to use Prometheus to export your API metrics.