Skip to main content
Version: development

Flow Label

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. Each flow is annotated with a set of Flow Labels, which are key-value pairs. For instance, if a flow is tagged with user_tier:gold, then user_tier is the label key and gold is the label value.

The following visualization depicts flows belonging to different control points across a distributed application, along with their associated flow labels.

graph TB subgraph Backend Services Gateway[Gateway Service] UserService[User Service] CatalogService[Catalog Service] CartService[Cart Service] OrderService[Order Service] PaymentService[Payment Service] DeliveryService[Delivery Service] end subgraph External Systems PaymentGateway[Payment Gateway] DeliveryProvider[Delivery Provider] end Gateway -->|User Login-> user_type:registered| UserService Gateway -->|Browse Catalog-> product_category:electronics| CatalogService Gateway -->|Add to Cart-> product_id:12345| CartService Gateway -->|Checkout-> cart_id:67890, user_type:registered| OrderService OrderService -->|Get User Info-> user_type:registered| UserService OrderService -->|Get Cart Info-> cart_id:67890| CartService OrderService -->|Process Payment-> payment_method:credit_card| PaymentService --> PaymentGateway OrderService -->|Arrange Delivery-> delivery_method:express| DeliveryService --> DeliveryProvider

Usage of Flow Labels​

Flow labels play a significant role in Aperture and serve various purposes:

  • The Selector can use flow labels to select specific flows, narrowing down the scope of Classifiers, Flux Meters, and other components.
  • Flow labels help map a flow to a specific Workload, providing context and aiding in workload identification.
  • Flow labels are instrumental in mapping flows to unique users or entities, allowing for the allocation of rate limit quotas per label key. This allocation is utilized by the Rate Limiter and Quota Scheduler components, enabling effective management of traffic and resource allocation based on these labels.

Flow Label Sources​

Flows are annotated with Flow Labels based on four sources:

  • Request labels
  • Baggage
  • Classifiers
  • Aperture SDKs.

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 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

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 Preview of Flow Labels​

Discover labels flowing through services and control points using aperturectl.

For example:

aperturectl flow-control preview --kube checkout-app.checkout-service.svc.cluster.local ingress

Returns:

{
  "samples": [
    {
      "labels": {
        "http.flavor": "1.1",
        "http.host": "checkout-app.checkout-service.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/checkout-app.checkout-service.svc.cluster.local/ingress?samples=1

Telemetry and Flow Labels​

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.

Label Precedence​

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

  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.