Skip to main content
Version: 2.6.0

Flow Label

what's a flow?

A flow is the fundamental unit of work from the perspective of an Aperture Agent. It could be an API call, a feature, or even a database query. A flow in Aperture is similar to OpenTelemetry span.

Every flow is annotated with a set of Flow Labels. Each Flow Label is a key:value pair. If a flow is annotated with user_tier:gold label, then user_tier is a label key and gold is a label value.

Flow Labels are used in different ways in Aperture:

Sources​

Flows are annotated with Flow Labels based on four sources: request labels, baggage, flow classifiers, and explicit labels from the Aperture SDK call.

Request labels​

For each HTTP Control Point (where flows are HTTP or gRPC requests), some basic metadata is available as request labels. These are http.method, http.target, http.host, http.scheme, http.request_content_length and http.flavor. Additionally, all (non-pseudo) headers are available as http.request.header.header_name, e.g. http.request.header.user_agent (note the snake_case!). The values of these labels are described by OpenTelemetry semantic conventions for HTTP spans. The only exception is the http.host attribute, which is equal to the host or authority header. This is similar to the net.peer.name OTel attribute.

Baggage​

Baggage propagation is a powerful concept that allows attaching metadata to a whole request chain or to a whole trace. If you already have baggage propagation configured in your system, you can access the baggage as flow labels. This is supported on service-mesh (Envoy) and web framework-based control point insertion.

  • HTTP: Baggage is pulled from the baggage header.
  • Feature: Baggage is automatically pulled from context on each Check() call. This is assuming you're using the OpenTelemetry library to manage the baggage.

Baggage members are mapped to Flow Labels 1:1–keys become label keys, values become label values (properties are ignored).

Read more about baggage propagation on: Baggage | OpenTelemetry.

Classifiers​

When the labels you need aren't already present in baggage, nor as request labels, you can create a Classifier to inject new labels into the system. Since the Classifier also injects the label into baggage by default, this means you can set or extract the label in a different place than where it is consumed (assuming you have baggage propagation configured throughout your system).

Aperture SDKs​

The Aperture SDKs, in addition to automatically using baggage from context, also takes an explicit labels map in the Check() call.

Live Previewing Flow Labels​

You can discover the labels flowing through services and control points using aperturectl.

For example:

aperturectl flow-control preview --kube service1-demo-app.demoapp.svc.cluster.local ingress

Returns:

{
  "samples": [
    {
      "labels": {
        "http.flavor": "1.1",
        "http.host": "service1-demo-app.demoapp.svc.cluster.local",
        "http.method": "POST",
        "http.request.header.content_length": "201",
        "http.request.header.content_type": "application/json",
        "http.request.header.cookie": "session=eyJ1c2VyIjoia2Vub2JpIn0.YbsY4Q.kTaKRTyOIfVlIbNB48d9YH6Q0wo",
        "http.request.header.user_agent": "k6/0.42.0 (https://k6.io/)",
        "http.request.header.user_id": "14",
        "http.request.header.user_type": "guest",
        "http.request.header.x_forwarded_proto": "http",
        "http.request.header.x_request_id": "3958dad8-eb71-47f0-a9f6-500cccb097d2",
        "http.request_content_length": "0",
        "http.scheme": "http",
        "http.target": "/request",
        "user_type": "guest"
      }
    }
  ]
}

Alternatively, you can use the Introspection API directly on a aperture-agent local to the service instances (pods):

curl -X POST localhost:8080/v1/flowcontrol/preview/labels/service1-demo-app.demoapp.svc.cluster.local/ingress?samples=1

Telemetry​

Telemetry data is extracted out of flows for further processing. This data is collected from the following sources:

Aperture uses OpenTelemetry's robust pipelines for receiving the telemetry data and producing other streams of data from it.

Metrics​

Prometheus metrics are generated from the received telemetry data. Along the path of the flows, telemetry data is tagged by the Flux Meters and workloads that matched.

OLAP style telemetry​

OLAP style telemetry data is generated as OpenTelemetry logs and is saved in an OLAP database. This is done by creating multidimensional roll ups from flow labels.

OLAP style telemetry does not work well with extremely high-cardinality labels, therefore, if an extremely high-cardinality label is detected, some of its values might be replaced with the REDACTED_VIA_CARDINALITY_LIMIT string.

Default labels​

These are protocol-level labels (For example: HTTP, network) extracted by the configured service mesh/middleware and are available to be referenced in Label Matcher, except for a few high-cardinality ones.

Labels extracted from baggage​

These are Flow Labels mapped from baggage.

Labels defined by user​

These are labels provided by Classifiers in case of service mesh/middleware integration, or explicitly at flow creation in Aperture SDK.

note

In the case of a clash, the Flow Label will be applied in the following precedence over:

  1. User-defined
  2. Baggage
  3. Default

Interaction with FluxNinja ARC Extension​

All the flow Labels are used as labels of flow events. These events are rolled up and sent to the analytics database in the FluxNinja ARC. This allows:

  • For the Flow Labels to be used as filters or group-by
  • To see analytics for each Flow Label, for example: distribution of its values
note

For Classifier created labels, you can disable this behavior by setting hidden: true in the classification rule.