본문으로 건너뛰기
번역된 페이지

이 페이지는 AI의 도움을 받아 영어에서 번역되었습니다. 두 내용이 다를 경우 영어 버전을 기준으로 합니다.

OTel 백엔드 레시피

참고 항목:
[출력 모드] [exec]

stackql exec --output otel 명령은 쿼리를 타임스탬프가 지정된 스냅샷으로 변환합니다. 행당 1개의 OpenTelemetry 로그 레코드와 문당 1개의 완료 레코드가 생성되며, 모든 레코드에 stackql.snapshot.id, stackql.query.hash, stackql.row.fingerprint 상관 키가 포함됩니다. otel 출력을 참조하세요. 이 페이지에서는 이 형식이 염두에 두고 설계된 두 백엔드에서 해당 레코드를 처음부터 끝까지 다룹니다: ClickHouse(ClickStack 포함)의 형식이 지정된 인벤토리 테이블, 그리고 Datadog의 로그 쿼리와 모니터입니다. 마지막 섹션은 각 실행에 트레이스 ID와 리소스 속성을 부여하는 예약된 CI 작업입니다.

레시피에서는 두 가지 반복 쿼리를 사용합니다. 하나는 Compute Engine 인스턴스의 인벤토리이고, 다른 하나는 프로젝트의 IAM 바인딩을 보안 주체 및 역할당 1행으로 펼친 것입니다. 두 쿼리 모두 identity 열을 프로젝션합니다. 이 열은 백엔드가 리소스를 추적하는 키(id, arn, selfLink 또는 복합 키의 경우 연결한 값)이며, 지문은 값입니다.

-- inventory: one row per instance
select id as identity, name, status, machineType, zone
from google.compute.instances
where project = 'stackql-demo' and zone = 'australia-southeast1-a';

-- entitlements: one row per principal and role
select iam.role || '/' || split_part(json_each.value, ':', 2) as identity,
iam.role, split_part(json_each.value, ':', 2) as principal
from google.cloudresourcemanager.projects_iam_policies iam, json_each(members)
where projectsId = 'stackql-demo';

각 쿼리에는 안정적인 stackql.query.hash 값이 있으며, 레시피는 이 값으로 필터링하므로 하나의 시리즈는 하나의 반복 쿼리로만 구성됩니다. ClickHouse에서는 {query_hash:String} 형식의 쿼리 매개 변수를 사용하거나, 완료 레코드의 해시를 붙여 넣으세요.

ClickHouse​

ClickStack에 포함된 OpenTelemetry Collector의 ClickHouse 익스포터는 로그 레코드를 otel_logs 테이블에 저장합니다. 이때 속성은 Timestamp, Body, TraceId, ScopeName 열과 함께 문자열 맵(ResourceAttributes, LogAttributes)으로 저장됩니다. 익스포터의 대상을 ClickStack의 OTLP 수집 엔드포인트 또는 Collector로 지정하세요:

OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod,stackql.job=gce-inventory \
stackql exec --output otel -f instances.otlp.jsonl \
--otel.config '{ "exporter": { "endpoint": "http://clickstack.example:4318/v1/logs", "headers": { "authorization": "'"$CLICKSTACK_INGESTION_KEY"'" } } }\' \
"select id as identity, name, status, machineType, zone from google.compute.instances \
where project = 'stackql-demo' and zone = 'australia-southeast1-a'"

형식이 지정된 인벤토리 테이블​

otel_logs 테이블을 직접 쿼리해도 되지만, 그러면 모든 질문에서 맵 조회 비용이 발생합니다. 구체화된 뷰는 행 레코드를 (query_hash, identity, snapshot_time) 키를 사용하는 형식이 지정된 테이블로 옮깁니다:

CREATE TABLE stackql_inventory
(
snapshot_time DateTime64(9),
snapshot_id String,
query_hash String,
provider LowCardinality(String),
service LowCardinality(String),
resource LowCardinality(String),
identity String,
fingerprint String,
attributes Map(LowCardinality(String), String),
document String,
environment LowCardinality(String),
trace_id String
)
ENGINE = MergeTree
ORDER BY (query_hash, identity, snapshot_time);

CREATE MATERIALIZED VIEW stackql_inventory_mv TO stackql_inventory AS
SELECT
Timestamp AS snapshot_time,
LogAttributes['stackql.snapshot.id'] AS snapshot_id,
LogAttributes['stackql.query.hash'] AS query_hash,
LogAttributes['stackql.provider'] AS provider,
LogAttributes['stackql.service'] AS service,
LogAttributes['stackql.resource'] AS resource,
LogAttributes['identity'] AS identity,
LogAttributes['stackql.row.fingerprint'] AS fingerprint,
LogAttributes AS attributes,
Body AS document,
ResourceAttributes['deployment.environment'] AS environment,
TraceId AS trace_id
FROM otel_logs
WHERE ScopeName = 'github.com/stackql/stackql/internal/stackql/output'
AND mapContains(LogAttributes, 'stackql.row.index');

완료 레코드는 별도의 작은 테이블에 저장됩니다. 이 테이블은 아래의 모든 레시피에서 "최신 스냅샷"의 의미를 정의합니다. 스냅샷은 완료 레코드가 도착한 후에야 유효한 것으로 간주되므로, 도중에 실패한 실행을 자산이 줄어든 것으로 오인하는 일이 없습니다.

CREATE TABLE stackql_snapshots
(
snapshot_time DateTime64(9),
snapshot_id String,
query_hash String,
query String,
rows_returned UInt32,
duration_ms UInt32,
environment LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (query_hash, snapshot_time);

CREATE MATERIALIZED VIEW stackql_snapshots_mv TO stackql_snapshots AS
SELECT
Timestamp AS snapshot_time,
LogAttributes['stackql.snapshot.id'] AS snapshot_id,
LogAttributes['stackql.query.hash'] AS query_hash,
LogAttributes['stackql.query'] AS query,
toUInt32OrZero(LogAttributes['stackql.rows_returned']) AS rows_returned,
toUInt32OrZero(LogAttributes['stackql.duration_ms']) AS duration_ms,
ResourceAttributes['deployment.environment'] AS environment
FROM otel_logs
WHERE ScopeName = 'github.com/stackql/stackql/internal/stackql/output'
AND LogAttributes['stackql.snapshot.complete'] = 'true';

구체화된 뷰는 생성된 후에 삽입된 행만 인식합니다. 그 전에 저장된 레코드는 뷰와 동일한 SELECT 쿼리를 사용하는 INSERT INTO ... SELECT 문으로 백필하세요.

리소스별 최신 상태​

현재 자산은 최신 완료 스냅샷의 행 집합입니다:

WITH (SELECT snapshot_id FROM stackql_snapshots WHERE query_hash = {query_hash:String}
ORDER BY snapshot_time DESC LIMIT 1) AS latest
SELECT identity, attributes['name'] AS name, attributes['status'] AS status, document
FROM stackql_inventory
WHERE snapshot_id = latest
ORDER BY identity;

이후 사라진 리소스를 포함하여 한 번이라도 확인된 모든 리소스의 마지막으로 알려진 상태를 구하려면 argMax 함수로 집계하세요:

SELECT
identity,
argMax(document, snapshot_time) AS document,
argMax(fingerprint, snapshot_time) AS fingerprint,
max(snapshot_time) AS last_seen
FROM stackql_inventory
WHERE query_hash = {query_hash:String}
GROUP BY identity
ORDER BY last_seen DESC;

두 스냅샷 간 드리프트​

두 스냅샷을 identity 기준으로 조인합니다. 지문이 다르면 변경이고, 한쪽이 없으면 나타나거나 사라진 리소스입니다:

WITH
(SELECT snapshot_id FROM stackql_snapshots WHERE query_hash = {query_hash:String}
ORDER BY snapshot_time DESC LIMIT 1) AS latest,
(SELECT snapshot_id FROM stackql_snapshots WHERE query_hash = {query_hash:String}
ORDER BY snapshot_time DESC LIMIT 1 OFFSET 1) AS previous
SELECT
if(n.identity != '', n.identity, p.identity) AS identity,
multiIf(p.identity = '', 'appeared', n.identity = '', 'disappeared', 'changed') AS change,
p.document AS before,
n.document AS after
FROM (SELECT identity, fingerprint, document FROM stackql_inventory WHERE snapshot_id = latest) AS n
FULL OUTER JOIN
(SELECT identity, fingerprint, document FROM stackql_inventory WHERE snapshot_id = previous) AS p
ON n.identity = p.identity
WHERE n.fingerprint != p.fingerprint
ORDER BY change, identity;

임의의 두 스냅샷 ID로 바꾸면 임의의 두 시점을 비교할 수 있습니다. 한쪽만 필요한 경우 같은 질문은 안티 조인이 됩니다:

-- appeared since the previous snapshot
SELECT n.identity, n.document
FROM (SELECT identity, document FROM stackql_inventory WHERE snapshot_id = latest) AS n
LEFT ANTI JOIN (SELECT identity FROM stackql_inventory WHERE snapshot_id = previous) AS p
ON n.identity = p.identity;

-- disappeared since the previous snapshot
SELECT p.identity, p.document
FROM (SELECT identity, document FROM stackql_inventory WHERE snapshot_id = previous) AS p
LEFT ANTI JOIN (SELECT identity FROM stackql_inventory WHERE snapshot_id = latest) AS n
ON p.identity = n.identity;

change 열은 프로젝션 범위 안의 드리프트를 나타냅니다. SELECT 문에서 제외된 열은 변경을 일으킬 수 없으므로, name 열과 status 열만 프로젝션하는 쿼리는 상태 변경만 보고합니다.

사용 권한 이력​

사용 권한 쿼리에서 identity는 보안 주체와 역할의 쌍이므로, 인벤토리 테이블에서 한 쌍의 타임라인이 곧 해당 사용 권한의 수명입니다:

WITH (SELECT max(snapshot_time) FROM stackql_snapshots WHERE query_hash = {query_hash:String}) AS latest_time
SELECT
attributes['principal'] AS principal,
attributes['role'] AS role,
min(snapshot_time) AS first_seen,
max(snapshot_time) AS last_seen,
max(snapshot_time) < latest_time AS revoked
FROM stackql_inventory
WHERE query_hash = {query_hash:String}
GROUP BY principal, role
ORDER BY last_seen DESC, principal, role;

first_seen 열과 last_seen 열은 해지되었다가 나중에 다시 부여된 권한을 하나의 기간으로 합칩니다. 공백이 중요한 경우 같은 그룹화에 groupArray(snapshot_time) 함수를 사용하면 해당 쌍이 존재했던 모든 스냅샷이 나열됩니다. 이 페이지의 다른 모든 내용은 그대로 적용됩니다. 사용 권한 쿼리에 드리프트 레시피를 적용하면 두 실행 사이의 권한 부여와 해지가 나열됩니다.

Datadog​

레코드를 Datadog Agent의 OTLP 리시버(Agent의 otlp_config 설정에서 HTTP 리시버를 활성화, 포트 4318) 또는 Datadog 익스포터를 실행하는 OpenTelemetry Collector의 OTLP 리시버로 보내세요. Datadog 자체 OTLP 수집 엔드포인트는 API 키를 헤더로 받아 레코드를 직접 수신합니다. 리전별 URL은 Datadog의 OTLP 수집 문서를 참조하세요.

OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod,stackql.job=gce-inventory \
stackql exec --output otel -f instances.otlp.jsonl \
--otel.config '{ "exporter": { "endpoint": "http://datadog-agent.example:4318/v1/logs" } }' \
"select id as identity, name, status, machineType, zone from google.compute.instances \
where project = 'stackql-demo' and zone = 'australia-southeast1-a'"
stackql exec --output otel ... \
--otel.config '{ "exporter": { "endpoint": "<regional OTLP logs intake URL>", "headers": { "dd-api-key": "'"$DD_API_KEY"'" } } }'

속성 매핑​

OpenTelemetryDatadog
service.name 리소스 속성service 태그(stackql 또는 OTEL_SERVICE_NAME)
deployment.environment 리소스 속성env 태그
cloud.provider, cloud.account.id, cloud.region, cloud.availability_zone 및 기타 리소스 속성로그 속성(예: @cloud.account.id)
stackql.* 로그 속성로그 속성(예: @stackql.snapshot.id). 필터링에 사용하는 속성에는 패싯을 추가하세요
행의 열(identity, name, status, ...)열 이름을 사용한 로그 속성(예: @status)
레코드 본문message, JSON 형식의 행
traceId, spanIdtrace_id, span_id: 한 번의 실행에 속한 모든 문을 연결

로그 쿼리​

Datadog은 존재 여부와 이력에 관한 질문에 답합니다. 스냅샷 간 조인은 ClickHouse에서 수행하거나, Collector를 통해 같은 스트림을 두 백엔드 모두에 팬아웃하여 수행합니다.

# completion records of one recurring query, newest first: the latest snapshot id
service:stackql @stackql.snapshot.complete:true @stackql.query.hash:<hash>

# the rows of one snapshot
service:stackql @stackql.query.hash:<hash> @stackql.snapshot.id:<snapshot id>

# the timeline of one resource; a new fingerprint value is a change
service:stackql @identity:<instance id>

# every principal that has held a role, grouped by @principal in Log Analytics;
# the first and last log in a group are first seen and last seen
service:stackql @stackql.query.hash:<entitlements hash> @role:roles/owner

완료 레코드에 대한 모니터는 파이프라인 자체를 모니터링합니다. service:stackql @stackql.snapshot.complete:true @stackql.rows_returned:0 쿼리에 대한 로그 모니터는 비어 있는 인벤토리를 감지하고, service:stackql @stackql.snapshot.complete:true @stackql.job:gce-inventory 쿼리에 "no data" 조건을 설정한 모니터는 실행되지 않은 예약 실행을 감지합니다.

예약된 CI​

예약된 작업이 시리즈를 만듭니다. 이 예제는 GitHub Actions에서 두 쿼리를 매시간 실행합니다. 익스포터는 OTEL_CONFIG 변수에 한 번 구성되어 --otel.config 플래그로 전달되고, TRACEPARENT 변수는 한 실행의 모든 문에 동일한 트레이스 ID를 부여하며, OTEL_RESOURCE_ATTRIBUTES 변수는 모든 레코드에 환경, 작업 이름, 실행 ID를 기록합니다. 또한 .otlp.jsonl 파일은 아티팩트로 보관되므로 푸시가 실패해도 사본이 남습니다.

name: cloud-inventory
on:
schedule:
- cron: '0 * * * *'
workflow_dispatch:
jobs:
snapshot:
runs-on: ubuntu-latest
env:
GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}
OTEL_CONFIG: '{ "exporter": { "endpoint": "${{ vars.OTLP_LOGS_ENDPOINT }}", "headers": { "authorization": "${{ secrets.OTLP_INGESTION_KEY }}" } } }'
OTEL_RESOURCE_ATTRIBUTES: deployment.environment=prod,stackql.job=cloud-inventory,stackql.run=${{ github.run_id }}
steps:
- uses: stackql/setup-stackql@v2
- name: snapshot
run: |
export TRACEPARENT="00-$(openssl rand -hex 16)-$(openssl rand -hex 8)-01"
stackql exec --output otel -f instances.otlp.jsonl --otel.config "$OTEL_CONFIG" \
"select id as identity, name, status, machineType, zone from google.compute.instances \
where project = 'stackql-demo' and zone = 'australia-southeast1-a'"
stackql exec --output otel -f entitlements.otlp.jsonl --otel.config "$OTEL_CONFIG" \
"select iam.role || '/' || split_part(json_each.value, ':', 2) as identity, \
iam.role, split_part(json_each.value, ':', 2) as principal \
from google.cloudresourcemanager.projects_iam_policies iam, json_each(members) \
where projectsId = 'stackql-demo'"
- uses: actions/upload-artifact@v4
with:
name: inventory-${{ github.run_id }}
path: "*.otlp.jsonl"

다른 스케줄러에서 같은 작업을 실행할 때도 플래그 하나와 환경 변수 2개만 있으면 됩니다. TRACEPARENT 변수는 선택 사항입니다. 이 변수가 없으면 각 stackql exec 프로세스가 자체 트레이스 ID를 생성하며, 이 ID는 해당 프로세스가 실행한 문끼리만 공유합니다. 따라서 위 실행의 두 문은 서로 다른 트레이스 ID를 갖게 됩니다.