OTCA — OpenTelemetry Certified Associate

Six orders, but the dashboard drew nine

한국어 원문으로 표시합니다.

목표

실제 OpenTelemetry Python SDK 로 리더의 temporality, 기본 히스토그램 경계, 뷰로 경계·속성·버리기를 바꾸는 방법, 비동기 계측기의 보고 방식을 차례로 재고, 세 뷰를 한 MeterProvider 에 조립합니다.

왜 중요한가

같은 카운터라도 누적(cumulative)으로 보내느냐 델타(delta)로 보내느냐에 따라 백엔드가 해석해야 하는 뜻이 달라집니다. 둘을 섞어 읽으면 주문이 두 번 세어지고, 초 단위 값을 밀리초용 기본 경계에 넣으면 히스토그램이 한 칸에 몰려 분위수가 무의미해집니다. 고객 ID 같은 속성은 데이터 포인트를 늘려 비용을 키웁니다. 계측 코드를 고치지 않고 SDK 설정(리더·뷰)으로 이것을 바로잡는 것이 API 와 SDK 를 나눈 이유입니다.

준비된 환경

/opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py init 이 /root/otca-metrics/ 에 shop.py(주문·장바구니·결제 시간·디버그 지표를 정해진 순서로 기록)와 pipeline.py(채울 함수 일곱 개)를 둡니다. /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show N 은 여러분의 pipeline.py 로 lab-dev 이미지의 OpenTelemetry Python SDK 1.44.0(/opt/otel-lab) MeterProvider 를 조립하고, shop 이 기록한 뒤 두 번 수집한 데이터 포인트를 출력합니다. 네트워크·컬렉터·API 키는 쓰지 않습니다. 채점기는 같은 SDK 로 여러분의 함수를 다시 실행해 동작과 적은 숫자를 대조합니다. 반드시 /opt/otel-lab/bin/python 으로 실행하세요.

단계

/opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py init 으로 재료를 만듭니다. /root/otca-metrics/pipeline.py 의 reader_cumulative() 가 기본 InMemoryMetricReader 를 돌려주게 고친 뒤 /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 1 을 실행하세요. shop.py 가 주문 3건을 기록하고 수집, 3건을 더 기록하고 다시 수집합니다. /root/otca-metrics/01-cumulative.txt 에 first=, second=(orders 합계)를 적으세요.
reader_delta() 가 Counter 만 DELTA 로 요청하는 리더를 돌려주게 고치고 /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 2 를 실행합니다. /root/otca-metrics/02-delta.txt 에 first=, second= 와 double_counted=(01 단계의 누적값 두 개를 델타로 착각해 더했을 때 대시보드가 그릴 합계)를 적으세요.
reader_all_delta() 가 Counter·UpDownCounter·Histogram·ObservableCounter 를 모두 DELTA 로 요청하게 고치고 /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 3 을 실행합니다. /root/otca-metrics/03-updown.txt 에 cumulative_second=(reader_delta 로 본 cart.items 두 번째 값)와 delta_second=(reader_all_delta 로 본 값)를 적으세요.
/opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 4 로 뷰 없이 수집한 checkout.duration(단위 s, 값 0.2·0.35·0.8·1.4)의 히스토그램을 봅니다. /root/otca-metrics/04-default-buckets.txt 에 boundaries=(기본 경계 개수), nonzero_bucket_index=(값이 들어간 버킷 위치, 0부터), nonzero_bucket_count= 를 적으세요.
views_buckets() 가 checkout.duration 에만 경계 0.25, 0.5, 1, 2 를 적용하는 View 목록을 돌려주게 고칩니다. /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 5 결과의 버킷 개수를 /root/otca-metrics/05-view-buckets.txt 에 bucket_counts=(쉼표로 구분, 마지막은 2 초과)로 적으세요. 다른 지표는 그대로 남아야 합니다.
views_cardinality() 가 orders 의 속성 키를 route 만 남기는 View 목록을 돌려주게 고칩니다. /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 6 을 보고 /root/otca-metrics/06-view-attributes.txt 에 points_before=(뷰 없는 첫 수집의 orders 포인트 수), points_after=, checkout_sum=(뷰를 건 첫 수집의 /checkout 값)을 적으세요.
register_async(meter, source) 에서 queue.processed 는 ObservableCounter 로 source.processed() 를, queue.depth 는 ObservableGauge 로 source.depth() 를 관측하게 합니다. /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 7(reader_all_delta 사용)을 보고 /root/otca-metrics/07-async.txt 에 processed_delta_second=, depth_second= 를 적으세요. source 는 호출마다 processed 10, 25 와 depth 7, 4 를 돌려줍니다.
provider(reader) 가 받은 리더와 뷰 세 개 — 05 단계 버킷, 06 단계 속성 줄이기, 그리고 debug.cache.lookups 를 버리는 DropAggregation — 를 가진 MeterProvider 를 돌려주게 고칩니다. 채점기는 reader_all_delta() 로 두 번 수집해 orders(route 기준 델타), checkout.duration(새 경계), cart.items, 버려진 debug 지표를 함께 확인합니다. /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 8 로 먼저 보세요.

참고

데이터 포인트의 temporality 는 리더가 요청한 값으로 결정됩니다. 계측 코드(shop.py)는 한 줄도 바뀌지 않습니다.
흔한 실수: preferred_temporality 에 Counter 만 넣고 UpDownCounter 도 바뀌었다고 기대하는 것, 비동기 카운터 콜백에서 증가분을 돌려주는 것, 뷰의 대상을 좁히지 않는 것.
이 실습은 InMemoryMetricReader 로 수집 시점을 직접 정합니다. 주기적 리더와 OTLP 익스포터의 기본 temporality 는 설정(OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE)에 따라 다릅니다.
Metrics data model · Metrics SDK

두 번 수집하면 3 다음 6

/opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py init 으로 재료를 만듭니다. /root/otca-metrics/pipeline.py 의 reader_cumulative() 가 기본 InMemoryMetricReader 를 돌려주게 고친 뒤 /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 1 을 실행하세요. shop.py 가 주문 3건을 기록하고 수집, 3건을 더 기록하고 다시 수집합니다. /root/otca-metrics/01-cumulative.txt 에 first=, second=(orders 합계)를 적으세요.

리더가 temporality 를 따로 요청하지 않으면 SDK 는 시작 시점부터의 누적값을 보냅니다.

델타로 받으면, 그리고 섞어 읽으면

reader_delta() 가 Counter 만 DELTA 로 요청하는 리더를 돌려주게 고치고 /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 2 를 실행합니다. /root/otca-metrics/02-delta.txt 에 first=, second= 와 double_counted=(01 단계의 누적값 두 개를 델타로 착각해 더했을 때 대시보드가 그릴 합계)를 적으세요.

preferred_temporality 는 계측기 클래스에서 temporality 로 가는 사전입니다. 누적값을 더하면 앞선 구간이 두 번 셉니다.

UpDownCounter 는 따로 요청해야 한다

reader_all_delta() 가 Counter·UpDownCounter·Histogram·ObservableCounter 를 모두 DELTA 로 요청하게 고치고 /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 3 을 실행합니다. /root/otca-metrics/03-updown.txt 에 cumulative_second=(reader_delta 로 본 cart.items 두 번째 값)와 delta_second=(reader_all_delta 로 본 값)를 적으세요.

reader_delta 는 Counter 만 바꿨습니다. 장바구니는 +5, -2 뒤에 +1 이 기록됩니다.

초 단위 값이 한 버킷에 몰렸다

/opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 4 로 뷰 없이 수집한 checkout.duration(단위 s, 값 0.2·0.35·0.8·1.4)의 히스토그램을 봅니다. /root/otca-metrics/04-default-buckets.txt 에 boundaries=(기본 경계 개수), nonzero_bucket_index=(값이 들어간 버킷 위치, 0부터), nonzero_bucket_count= 를 적으세요.

SDK 의 기본 경계는 밀리초 단위 지연을 염두에 둔 값입니다. 첫 경계와 두 번째 경계를 보세요.

뷰로 경계를 바꾸기

views_buckets() 가 checkout.duration 에만 경계 0.25, 0.5, 1, 2 를 적용하는 View 목록을 돌려주게 고칩니다. /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 5 결과의 버킷 개수를 /root/otca-metrics/05-view-buckets.txt 에 bucket_counts=(쉼표로 구분, 마지막은 2 초과)로 적으세요. 다른 지표는 그대로 남아야 합니다.

View 는 instrument_name 으로 대상을 고르고 aggregation 으로 집계를 바꿉니다. 대상을 고르지 않으면 모든 계측기에 걸립니다.

고객 ID 를 버리면 포인트가 줄어든다

views_cardinality() 가 orders 의 속성 키를 route 만 남기는 View 목록을 돌려주게 고칩니다. /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 6 을 보고 /root/otca-metrics/06-view-attributes.txt 에 points_before=(뷰 없는 첫 수집의 orders 포인트 수), points_after=, checkout_sum=(뷰를 건 첫 수집의 /checkout 값)을 적으세요.

데이터 포인트는 속성 조합마다 하나입니다. 남길 키만 고르면 나머지 키가 다른 측정은 합쳐지고 합계는 보존됩니다.

비동기 카운터는 누적값을 보고한다

register_async(meter, source) 에서 queue.processed 는 ObservableCounter 로 source.processed() 를, queue.depth 는 ObservableGauge 로 source.depth() 를 관측하게 합니다. /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 7(reader_all_delta 사용)을 보고 /root/otca-metrics/07-async.txt 에 processed_delta_second=, depth_second= 를 적으세요. source 는 호출마다 processed 10, 25 와 depth 7, 4 를 돌려줍니다.

비동기 카운터 콜백은 지금까지의 누적 절댓값을 돌려줍니다. 델타는 SDK 가 직전 관측과의 차이로 계산합니다. 게이지는 더하지 않습니다.

뷰 세 개를 한 프로바이더에

provider(reader) 가 받은 리더와 뷰 세 개 — 05 단계 버킷, 06 단계 속성 줄이기, 그리고 debug.cache.lookups 를 버리는 DropAggregation — 를 가진 MeterProvider 를 돌려주게 고칩니다. 채점기는 reader_all_delta() 로 두 번 수집해 orders(route 기준 델타), checkout.duration(새 경계), cart.items, 버려진 debug 지표를 함께 확인합니다. /opt/otel-lab/bin/python /opt/fixtures/otca_metrics_lab.py show 8 로 먼저 보세요.

뷰는 MeterProvider 를 만들 때 넘깁니다. 한 계측기에 뷰가 여럿 맞으면 스트림이 여럿 생기므로, 뷰마다 대상을 좁히세요.