Exemplars trong OpenTelemetry Metrics

Mục lụcCopy Anchor Link

• Exemplar là gì
  • Metric aggregate và measurement mẫu
  • Các trường của exemplar
• Exemplar nối metric với trace như thế nào
  • Luồng measurement đến backend
  • Use case histogram latency
  • Exemplar không phải trace sampling
• Filter và reservoir
  • Exemplar filter
  • Exemplar reservoir
  • Filtered attributes và rủi ro dữ liệu
• Bật exemplar theo cách vendor-neutral
  • Biến môi trường chuẩn
  • Cấu hình trong SDK
  • Khác biệt giữa các ngôn ngữ
• Cardinality, chi phí và giới hạn
  • Chi phí runtime và pipeline
  • Cardinality của metric không giống số exemplar
  • Temporality và chuyển đổi aggregation
• Backend support và cách xác minh
  • Caveat về backend
  • Kiểm tra ở nguồn
  • Kiểm tra qua OTLP và backend
• Failure modes thường gặp
• Checklist vận hành
• Tham khảo chính thức
• Bài liên quan

Exemplar là gìCopy Anchor Link

Exemplar là một data point mẫu của dữ liệu metric đã được aggregate. Nó giữ lại một measurement cụ thể để bổ sung context cho một con số tổng hợp.

Ví dụ, một Histogram có thể báo p95 = 240 ms cho hàng nghìn request. Histogram không nói request nào tạo ra một observation khoảng 2.400 ms. Exemplar có thể giữ chính observation đó cùng trace ID và span ID của request.

Metric aggregate và measurement mẫuCopy Anchor Link

Measurement là giá trị được ghi qua Metrics API. Ví dụ, ứng dụng gọi request_duration.record(2400, attributes, context) khi một request hoàn tất.

Aggregation là cách SDK gộp nhiều measurement thành metric data point. Với histogram, SDK giữ count, sum và các bucket thay vì gửi từng measurement.

Exemplar không thay thế aggregation. Nó là một đường dẫn chọn lọc nằm cạnh aggregation:

Một exemplar có thể hữu ích cho mọi metric. Nó không chỉ dành cho metric được tạo từ span. Tuy nhiên, khả năng nhảy sang trace cần active span context và một backend trace có dữ liệu tương ứng.

Các trường của exemplarCopy Anchor Link

Trong OTLP data model, exemplar nằm trong exemplars của metric data point. Các trường cốt lõi là:

trace_id và span_id là các định danh binary trong OTLP. Backend thường hiển thị chúng dưới dạng hex. Trace ID định danh toàn trace. Span ID định danh một operation trong trace.

JSON dưới đây là pseudocode gần với OTLP, không phải schema JSON đầy đủ của mọi exporter:

{
  "metric": {
    "name": "http.server.request.duration",
    "histogram": {
      "data_points": [
        {
          "attributes": {
            "http.request.method": "GET",
            "http.response.status_code": 200
          },
          "start_time_unix_nano": 1710000000000000000,
          "time_unix_nano": 1710000060000000000,
          "count": 1200,
          "sum": 148500,
          "exemplars": [
            {
              "filtered_attributes": {
                "http.route": "/checkout/{id}"
              },
              "time_unix_nano": 1710000042123456789,
              "as_double": 2400.0,
              "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
              "span_id": "00f067aa0ba902b7"
            }
          ]
        }
      ]
    }
  }
}

Trong ví dụ, 2400.0 dùng đơn vị do metric định nghĩa, chẳng hạn milliseconds. http.route là filtered attribute nếu View chỉ giữ hai attribute còn lại trên metric stream.

Exemplar nối metric với trace như thế nàoCopy Anchor Link

Exemplar tạo liên kết một chiều từ metric data point đến measurement cụ thể. Trace context được đọc tại thời điểm gọi API ghi measurement. SDK không chờ đến lúc span kết thúc mới tạo liên kết.

Luồng measurement đến backendCopy Anchor Link

Lifecycle điển hình có các bước sau:

1. Instrumentation nhận một request và tạo active span.
2. Ứng dụng đo latency rồi ghi measurement vào Histogram.
3. Exemplar filter quyết định measurement có đủ điều kiện hay không.
4. Nếu đủ điều kiện, exemplar reservoir có thể giữ hoặc thay thế sample đang có.
5. SDK aggregate toàn bộ measurement thành metric data point.
6. MetricReader collect data point và exemplar trong cùng khoảng thời gian.
7. Metric exporter gửi metric qua OTLP hoặc định dạng khác.
8. Collector có thể batch, filter, reaggregate hoặc chuyển tiếp dữ liệu.
9. Backend phải lưu và hiển thị exemplar để người dùng click sang trace.

Filter và reservoir nằm trong Metrics SDK. Trace exporter chạy một pipeline riêng. Vì vậy, việc reservoir giữ exemplar không có nghĩa trace exporter đã gửi span.

Use case histogram latencyCopy Anchor Link

Giả sử ứng dụng ghi duration của mọi request vào Histogram:

request_duration.record(
  value=2400,
  attributes={"route": "/checkout/{id}", "status": 200},
  context=current_context,
)

Metric aggregate có thể cho thấy bucket le=5000 tăng và p95 vượt ngưỡng. Reservoir có thể giữ measurement 2400 cùng trace ID T và span ID S.

Người điều tra thực hiện hai bước:

1. Mở exemplar trên biểu đồ latency.
2. Dùng trace_id=T để mở trace và xem span nào tạo ra latency.

Trace có thể cho thấy request bị chậm do payment retry hoặc database lock. Metric cho biết vấn đề phổ biến đến mức nào. Trace cho biết một execution đã xảy ra như thế nào.

Exemplar không bảo đảm đại diện cho percentile cụ thể. Reservoir chọn sample theo chính sách của SDK. Nếu cần tìm mọi request chậm hơn 2 s, hãy dùng metric alert, log hoặc tail-sampling policy bổ sung. Đừng coi một exemplar là bằng chứng duy nhất rằng mọi request trong bucket đều chậm.

Exemplar không phải trace samplingCopy Anchor Link

Hai cơ chế có quan hệ nhưng giải quyết hai bài toán khác nhau:

TraceBased thường chỉ cho measurement đi tiếp khi measurement nằm trong context của sampled parent span. Đây là một điều kiện eligibility, không phải lệnh bật sampling cho trace.

Các tình huống cần phân biệt:

• Không có active span: measurement vẫn có thể vào metric aggregate. Exemplar trace-based thường không được chọn. Với AlwaysOn, SDK có thể giữ exemplar nhưng không có trace/span ID để tạo liên kết.
• Có active span nhưng trace không sampled: TraceBased không chọn measurement.
• Có exemplar và trace ID nhưng trace không được export hoặc đã hết retention: liên kết tồn tại về mặt dữ liệu nhưng không mở được trace.
• Trace được giữ nhưng reservoir không chọn measurement: trace có trong backend nhưng metric chart không có exemplar trỏ tới trace đó.

Filter và reservoirCopy Anchor Link

OpenTelemetry tách việc chọn exemplar thành hai lớp. Filter giới hạn measurement được phép tham gia. Reservoir quyết định sample nào thực sự được giữ.

Exemplar filterCopy Anchor Link

OpenTelemetry Metrics SDK phải hỗ trợ ba filter dựng sẵn:

Tên trong API có thể viết AlwaysOn, AlwaysOff, TraceBased. Tên trong biến môi trường chuẩn dùng chữ thường với dấu gạch dưới.

Filter không phải reservoir. always_on không có nghĩa mọi measurement sẽ xuất hiện trong OTLP. Nó chỉ offer mọi measurement cho reservoir. Reservoir vẫn có thể giữ một số lượng cố định hoặc chọn theo aggregation.

Exemplar reservoirCopy Anchor Link

Reservoir là bộ nhớ chọn lọc gắn với từng metric timeseries data point. Một metric timeseries được xác định bởi metric name, resource, scope và tập defining attributes. SDK tạo reservoir riêng cho mỗi timeseries đã biết.

Reservoir nhận measurement, value, attributes, context và timestamp. Nó có thể:

• giữ sample đầu tiên hoặc sample ngẫu nhiên;
• thay sample cũ bằng sample mới;
• giữ một sample phù hợp với bucket histogram;
• từ chối measurement dù filter đã cho phép;
• trả các exemplar đã tích lũy khi MetricReader collect.

Hai loại reservoir mặc định được specification nêu là:

Mặc định được khuyến nghị hiện hành là:

• Explicit bucket histogram có hơn một bucket dùng reservoir căn theo bucket.
• Base-2 exponential histogram dùng fixed-size reservoir với kích thước min(max_buckets, 20).
• Các aggregation còn lại dùng fixed-size reservoir.

Đây là default của SDK specification. Kích thước và đặc tính thống kê cụ thể có thể khác theo implementation và có thể thay đổi trong minor release. Không nên viết dashboard phụ thuộc vào việc reservoir luôn chọn cùng một measurement.

Pseudocode minh họa thứ tự xử lý:

on_record(measurement, context):
    aggregation.add(measurement.value, measurement.attributes)

    if exemplar_filter.should_sample(measurement, context) == false:
        return

    ts = series_for(measurement.attributes)
    exemplar = {
        value: measurement.value,
        time: measurement.timestamp,
        filtered_attributes: attributes_not_kept_by(ts),
        trace_id: context.active_span.trace_id,
        span_id: context.active_span.span_id,
    }
    ts.exemplar_reservoir.offer(exemplar)

on_collect():
    point = aggregation.collect()
    point.exemplars = reservoir.collect()
    return point

Pseudocode không phải API của một ngôn ngữ cụ thể. Nó nhấn mạnh rằng aggregation vẫn nhận measurement ngay cả khi filter loại measurement khỏi exemplar.

Filtered attributes và rủi ro dữ liệuCopy Anchor Link

Metric data point thường giữ một allow-list attribute để kiểm soát metric cardinality. Exemplar có thể giữ các attribute còn lại của measurement dưới filtered_attributes.

Ví dụ:

Measurement attributes:
  route       = /checkout/{id}
  tenant      = acme
  order_id    = 8f1...

Metric View giữ:
  route

Exemplar có thể giữ:
  tenant, order_id

Cơ chế này hữu ích khi cần biết sample cụ thể thuộc tenant nào mà không muốn đưa tenant vào mọi metric timeseries. Nó cũng có thể làm lộ dữ liệu nhạy cảm trên một đường dẫn mà người vận hành không ngờ tới.

Trước khi bật exemplar, hãy:

• allow-list attributes được phép xuất hiện trong measurement;
• loại secret, token, cookie, body và PII ngay tại instrumentation hoặc filter;
• giới hạn độ dài và số lượng filtered attributes theo SDK;
• kiểm tra quyền truy cập của người có thể xem metric backend;
• xác nhận Collector processor không vô tình giữ dữ liệu đã định redaction.

Nếu chính sách là “không được export attribute này ở bất kỳ đâu”, không dùng View đơn độc. Dùng AlwaysOff hoặc custom filter/reservoir đã được kiểm thử.

Bật exemplar theo cách vendor-neutralCopy Anchor Link

Cấu hình portable nên có hai phần: filter trong Metrics SDK và pipeline trace có propagation đúng. Exemplar không thể tạo liên kết hữu ích nếu ứng dụng không có active span hoặc trace backend không nhận trace.

Biến môi trường chuẩnCopy Anchor Link

Specification hiện hành định nghĩa biến:

export OTEL_METRICS_EXEMPLAR_FILTER=trace_based

Các giá trị chuẩn là:

Specification cho phép implementation hỗ trợ biến môi trường. Nó không bắt buộc mọi ngôn ngữ phải đọc biến này. Nếu implementation đọc biến, giá trị enum nên được xử lý không phân biệt hoa thường và giá trị không hợp lệ nên tạo warning rồi bỏ qua cấu hình.

Không có biến môi trường OpenTelemetry chuẩn tương đương cho kích thước hoặc loại ExemplarReservoir. Hãy dùng API của SDK, View hoặc cấu hình riêng của implementation cho phần đó.

Để tắt exemplar một cách rõ ràng:

export OTEL_METRICS_EXEMPLAR_FILTER=always_off

Để bật mọi measurement vào eligibility trong môi trường lab:

export OTEL_METRICS_EXEMPLAR_FILTER=always_on

always_on có thể làm tăng payload và đưa filtered attributes vào pipeline. Không bật nó trên toàn bộ production traffic chỉ để “chắc chắn có exemplar”.

Cấu hình trong SDKCopy Anchor Link

Cách vendor-neutral về mặt ý tưởng là:

meter_provider = MeterProvider(
    exemplar_filter = TraceBased,
    metric_reader = PeriodicExportingMetricReader(otlp_metric_exporter),
    views = [
        View(
            instrument = "http.server.request.duration",
            aggregation = ExplicitBucketHistogram,
            attribute_keys = ["http.request.method", "http.response.status_code"]
        )
    ]
)

Khi chọn TraceBased, hãy đồng thời cấu hình:

• TracerProvider có sampler phù hợp với mục tiêu giữ trace.
• Propagator inject và extract traceparent ở mọi service boundary.
• Metric exporter gửi OTLP data point có exemplars.
• Trace exporter gửi spans tới cùng hệ thống hoặc hệ thống có liên kết.
• Graceful shutdown gọi ForceFlush hoặc Shutdown để không mất batch cuối.

Nếu muốn custom reservoir, chọn reservoir theo aggregation. Histogram latency thường hưởng lợi từ reservoir hiểu bucket boundaries. Đừng dùng một reservoir không giới hạn cho mọi timeseries.

Khác biệt giữa các ngôn ngữCopy Anchor Link

Bảng dưới đây mô tả điểm khác nhau cần kiểm tra ở các SDK chính. API và mức hỗ trợ có thể thay đổi theo phiên bản.

Tóm lại, cùng một giá trị trace_based không đảm bảo cùng một tên hàm. Pin phiên bản SDK và chạy một smoke test trên từng ngôn ngữ trong topology đa ngôn ngữ.

Cardinality, chi phí và giới hạnCopy Anchor Link

Exemplar được thiết kế để giảm chi phí so với gửi mọi measurement, nhưng không miễn phí. Cần xem chi phí ở cả process, network, Collector và backend.

Chi phí runtime và pipelineCopy Anchor Link

Chi phí có thể phát sinh từ:

• đọc active context và trace/span ID ở mỗi lần ghi;
• tạo hoặc sao chép attributes cho measurement đủ điều kiện;
• state của reservoir cho từng timeseries;
• CPU để chạy reservoir sampling;
• bytes OTLP bổ sung cho exemplar và filtered attributes;
• memory và queue trong MetricReader, Collector và exporter;
• storage, indexing và liên kết trace ở backend;
• thao tác truy vấn hoặc hiển thị exemplar trong giao diện.

AlwaysOff phải tránh overhead exemplar sampling theo SDK specification. Với traffic lớn, filter TraceBased thường giảm số measurement được offer, nhưng không loại bỏ hoàn toàn chi phí đọc context nếu SDK phải đánh giá filter.

Cardinality của metric không giống số exemplarCopy Anchor Link

Metric cardinality là số timeseries khác nhau do tập attributes của metric tạo ra. Exemplar count là số sample nằm trong các data point của những timeseries đó.

Exemplar không tự tạo một metric timeseries mới. Tuy nhiên, nó vẫn có thể làm tăng chi phí vì:

• mỗi timeseries có reservoir riêng;
• nhiều timeseries đồng nghĩa nhiều reservoir state;
• filtered attributes có thể có giá trị cardinality cao;
• backend có thể index trace ID, span ID hoặc exemplar labels;
• một metric với user.id đã tạo quá nhiều timeseries trước khi exemplar được xét.

Thiết kế metric với attributes bounded như http.route và status code. Không đưa URL đầy đủ, order ID hoặc user ID vào defining attributes chỉ để tìm trace. Dùng filtered attributes có kiểm soát nếu thật sự cần context của sample.

Temporality và chuyển đổi aggregationCopy Anchor Link

Exemplar gắn với metric data point và nên nằm trong khoảng thời gian mà point đó đại diện. Với Sum hoặc Histogram, start_time_unix_nano và time_unix_nano mô tả cửa sổ aggregation. Exemplar có timestamp measurement riêng.

Một pipeline có thể dùng delta hoặc cumulative temporality:

• Delta point thường đại diện một khoảng không chồng lấp với lần export trước.
• Cumulative point tiếp tục từ một start time cố định.
• SDK phải collect exemplar phù hợp với point và implementation có thể reset reservoir khi collect delta.
• Collector hoặc backend có thể reaggregate, đổi temporality hoặc đổi bucket.

Khi chuyển đổi, không được giả định exemplar cũ luôn có thể chuyển nguyên vẹn. Một processor có thể drop exemplar khi merge data point, đổi aggregation hoặc không biết cách giữ quan hệ timestamp. Backend cũng có thể chỉ hỗ trợ exemplar ở một temporality hoặc một metric type.

Nói ngắn gọn: nếu exemplar biến mất sau khi đổi delta sang cumulative, kiểm tra cả SDK, Collector processor, exporter và backend. Đừng chỉ kiểm tra code ghi measurement.

Backend support và cách xác minhCopy Anchor Link

OTLP có trường exemplar trong NumberDataPoint, HistogramDataPoint và các metric point phù hợp. Tuy nhiên, “OTLP nhận được exemplar” và “UI cho click sang trace” là hai điều kiện khác nhau.

Caveat về backendCopy Anchor Link

Backend cần hỗ trợ đủ các bước sau:

1. Receiver không drop exemplars khi nhận OTLP.
2. Storage lưu value, timestamp, filtered attributes và trace/span IDs phù hợp.
3. Query API trả exemplar cùng metric series.
4. UI render exemplar hoặc cho phép cấu hình liên kết tới trace backend.
5. Trace backend có trace tương ứng và người dùng có quyền đọc nó.

Prometheus là ví dụ có caveat rõ ràng. Tài liệu OpenTelemetry .NET yêu cầu bật exemplar storage bằng --enable-feature=exemplar-storage và cấu hình Grafana để liên kết label trace_id tới Jaeger. Đây là yêu cầu của stack đó, không phải cấu hình vendor-neutral áp dụng cho mọi backend.

Một backend có thể hiển thị metric chính xác nhưng drop exemplar. Một Collector có thể export trace thành công nhưng exporter metrics không serialize exemplar. Một UI có thể nhận trace_id nhưng không biết URL hoặc datasource của trace.

Kiểm tra ở nguồnCopy Anchor Link

Bắt đầu với một test có dữ liệu dễ nhận biết:

1. Bật ConsoleMetricExporter hoặc OTLP tới Collector debug exporter.
2. Tạo một active span tên "exemplar-smoke-test".
3. Trong span, record Histogram value = 2400 với route cố định.
4. Gọi ForceFlush hoặc chờ một chu kỳ export.
5. Tìm metric data point có trường exemplars.
6. Đối chiếu value, timestamp, trace_id và span_id với active span.

Pseudocode:

with tracer.start_as_current_span("exemplar-smoke-test") as span:
    duration_ms.record(2400, {"route": "/exemplar-test"})
    expected_trace_id = span.context.trace_id
    expected_span_id = span.context.span_id

flush_metrics_and_traces()
assert exported_metric.histogram.data_points[*].exemplars contains:
    value == 2400
    trace_id == expected_trace_id
    span_id == expected_span_id

Nếu test không có trace_id, ghi lại các giá trị sau:

• filter thực tế sau khi environment và code cùng cấu hình;
• active span có phải current span không;
• span context có valid ID không;
• sampled flag có đúng yêu cầu của TraceBased không;
• metric reader đã collect sau thời điểm record chưa;
• reservoir có thể chọn sample value đó không.

Kiểm tra qua OTLP và backendCopy Anchor Link

Dùng một Collector debug pipeline trong môi trường kiểm soát:

receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [debug]

Schema cấu hình receiver có thể cần endpoint cụ thể theo bản Collector. Output debug không phải contract ổn định, nhưng cần tìm:

• metric name và metric type;
• data point attributes;
• data point start/end timestamp;
• exemplars;
• exemplar time_unix_nano, value, trace_id, span_id và filtered_attributes.

Sau đó kiểm tra backend theo hai lớp:

• Query metric và xác nhận exemplar xuất hiện tại timestamp/value mong đợi.
• Mở liên kết trace và xác nhận trace ID có trace, span ID có span tương ứng.

Chạy thêm các negative test:

Không kiểm tra bằng một request duy nhất để kết luận reservoir hoặc sampling xác suất. Một request chỉ kiểm tra wiring. Hãy tạo đủ traffic để kiểm tra tỷ lệ và độ ổn định của pipeline.

Failure modes thường gặpCopy Anchor Link

Checklist vận hànhCopy Anchor Link

• Metric là aggregation và exemplar chỉ là measurement mẫu bên cạnh aggregation.
• Đã chọn TraceBased, AlwaysOn hoặc AlwaysOff có chủ đích.
• Đã biết SDK ngôn ngữ đang dùng có đọc OTEL_METRICS_EXEMPLAR_FILTER không.
• Có active span tại lệnh record nếu cần trace/span ID.
• Trace context được propagate và sampler giữ trace theo mục tiêu.
• Không dùng trace sampling để suy ra metric error rate hoặc percentile.
• Đã kiểm soát filtered attributes, secret, PII và high-cardinality values.
• Reservoir có giới hạn và phù hợp với aggregation, đặc biệt histogram.
• Collector/exporter không drop exemplar khi batch hoặc convert temporality.
• Backend lưu exemplar và có trace datasource/link đúng.
• Đã kiểm tra cả OTLP payload lẫn UI backend.
• Đã chạy negative test cho no span, unsampled trace, AlwaysOff và backend drop.
• Đã gọi ForceFlush/Shutdown trong test và graceful shutdown production.

Tham khảo chính thứcCopy Anchor Link

• OpenTelemetry Metrics Data Model — Exemplars
• OpenTelemetry Metrics SDK — Exemplar, Filter và Reservoir
• OpenTelemetry SDK Environment Variables — OTEL_METRICS_EXEMPLAR_FILTER
• OpenTelemetry Metrics API — Measurement và Context
• OpenTelemetry Protocol — Metrics protobuf
• OpenTelemetry .NET — Using exemplars
• OpenTelemetry SDK configuration — Environment-variable compliance
• OpenTelemetry Concepts — Metrics

Bài liên quanCopy Anchor Link