ApiMetrics

Overview

A service can generate fine-grained api level metrics for ingress and well as egress requests into and outof the service.

Metrics are output with vhost.<service>.vcluster.<metricset>. and vhost.<service>-egress.vcluster.<metricset>. prefixes for requests in ingress and egress paths respectively.

Each metrics set includes the followings metrics

Metric	Type	Description
upstream_rq_<*xx>	Counter	Aggregate HTTP response codes (e.g., 2xx, 3xx, etc.)
upstream_rq_<*>	Counter	Specific HTTP response codes (e.g., 201, 302, etc.)
upstream_rq_retry	Counter	Total request retries
upstream_rq_retry_limit_exceeded	Counter	Total requests not retried due to exceeding the configured number of maximum retries
upstream_rq_retry_overflow	Counter	Total requests not retried due to circuit breaking or exceeding the retry budgets
upstream_rq_retry_success	Counter	Total request retry successes
upstream_rq_time	Histogram	Request time milliseconds
upstream_rq_timeout	Counter	Total requests that timed out waiting for a response
upstream_rq_total	Counter	Total requests initiated by the router to the upstream

Related envoy documentation can be found here and here

---

Config Reference

Click to expand!

# titanSideCars.ingress.routes[].
# titanSideCars.egress.routes[].
  match:      RouteMatch
  metrics:
    enabled:  bool
    name:     string

match

(RouteMatch, required)

metrics

(optional) Sets up metrics for requests that match corresponding route definition.
If missing, the metrics template parser will totally skip processing of this route entry.

metrics.enabled

(bool, default true) Controls generation of metrics for corresponding route definition

metrics.name

(string, required) Metrics name. Metrics are output with vhost.<service>.vcluster.<metricset>. and vhost.<service>-egress.vcluster.<metricset>. prefixes for requests in ingress and egress paths respectively. The metrics name maps to the metricsset component of the prefix.

---

Examples

Example 1

Configure metrics for incoming requests into demoapp service

# service: demoapp
titanSideCars:
  ingress:
    routes:
    - match:
        prefix: /demoapp/projects
        headers:
        - key: :method
          eq: POST
      metrics:
        name: create_project  # used as metricset-name
    - match:
        prefix: /demoapp/projects
        headers:
        - key: :method
          eq: GET
      metrics:
        name: get_project
    - match:
        prefix: /demoapp/projects
        headers:
        - key: :method
          eq: GET
        - key: x-client
          eq: democlient
      metrics:
        name: get_project_democlient

Above configuration will generate metrics with following prefixes

vhost.demoapp.vcluster.create_project.xxx
vhost.demoapp.vcluster.get_project.xxx
vhost.demoapp.vcluster.get_project_democlient.xxx

A request is matched against all entries in the routes array. Hence a request will contribute to the metrics set of each route entry that it matches. In above example, a request GET /demoapp/projects/demoproj with header x-client=democlient will match both second and thrid route entries and hence will contribute to metric sets get_project and get_project_democlient

Example 2

Configure metrics for outgoing requests out of demoapp service

# service: demoapp
titanSideCars:
  egress:
    routes:
    - match:
        prefix: /devices
        method: GET
      metrics:
        name: get_devices
    - match:
        prefix: /devices
        method: POST
      metrics:
        name: create_devices
    - metrics:
        name: users
      route:
        cluster: directory

Above configuration will generate metrics with following prefixes

vhost.demoapp-egress.vcluster.get_devices.xxx
vhost.demoapp-egress.vcluster.create_devices.xxx
vhost.demoapp-egress.vcluster.users.xxx

In above example, the first two routes explicitly specifiy the route match. For third route entry, the route definiton(s) will be picked from the directory cluster defintion.

A request is matched against all entries in the routes array and a request will contribute to the metrics bucket of each route entry that it matches.

How to use regular expression which will work in envoy?

# service: demoapp
titanSideCars:
  ingress:
    routes:
    - match:
        # Try to match http request DELETE /customers/hdegsdsad/domains/bdaerdaddd
        regex: /customers/[^/]+/domains/[^/]+$
        method: DELETE
      metrics:
        name: delete a domain  # used as metricset-name
    - match:
        # Try to match http request POST /customers/hdegsdsad/domains/bdaerdaddd/subscriptions
        regex: /customers/[^/]+/domains/[^/]+/subscriptions$
        headers:
        - key: :method
          eq: POST
      metrics:
        name: create_a_subscription_for_a_domain

---