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 example, if a flow is
user_tier is the label key and
the label value.
The following visualization depicts flows belonging to different control points across a distributed application, along with their associated flow labels.
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
- Aperture SDKs
For each HTTP Control Point (where flows are HTTP or gRPC
requests), some basic metadata is available as request labels. These are
http.flavor. Additionally, all (non-pseudo)
headers are available as
http.request.header.user_agent (note the
The values of these labels are described by OpenTelemetry semantic conventions
for HTTP spans. The only exception is the
attribute, which is equal to the host or authority header. This is similar to
net.peer.name OTel attribute.
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).
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).
The Aperture SDKs, in addition to automatically using baggage from context, also
takes an explicit
labels map in the
Live Preview of Flow Labels
Discover labels flowing through services and control points using
aperturectl flow-control preview --kube checkout-app.checkout-service.svc.cluster.local ingress
"http.request.header.user_agent": "k6/0.42.0 (https://k6.io/)",
Alternatively, you can use the
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:
- Traces from SDKs
- Stream of access logs from service mesh (refer to Istio Configuration)
- Stream of access logs from API Gateways
Aperture uses OpenTelemetry's robust pipelines for receiving the telemetry data and producing other streams of data from it.
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
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.
In case of a clash, the Flow Label will be applied in the following precedence order:
Interaction with FluxNinja 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 Aperture Cloud. 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
For Classifier created labels, you can disable this behavior by setting
hidden: true in the