Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

- Service map from complete trace counts: ClickHouse trace sources using the standard OTel exporter table now count service calls, database access, workloads and messaging across the whole one-hour window with bounded read-only aggregate queries (two, plus a third for span links when the table has them), instead of joining the newest 1,000 spans, so low-volume calls and databases no longer drop out and calls whose parent fell outside the sample no longer show as orphans. If an aggregate query fails, that rebuild falls back to the newest-span sample and is marked partial. Custom or generated ClickHouse queries and Tempo keep span sampling. The node cap keeps each kept database, queue or workload together with its caller. Prometheus/Mimir service-graph metrics add service-to-service calls only: rows Tempo marks as database, queue or uninstrumented-peer connections no longer appear as same-named services. Rebuild the datasource graph catalog (`datasource_index`) to pick up the new metric query.
- Web framework and runtime refresh: Next.js 16.4.5, React 19.3.1 and Node 26.13.0 retain authentication, ownership checks and standalone deployment; the request body guard uses the Next.js proxy convention. Refresh JavaScript/Python dependencies and AgentCore SDKs with compatibility pins, Terraform 1.17.1/provider locks, and Python 3.14 Lambda/container runtimes. The documentation guide builds and deploys on Node 26 with refreshed documentation security dependencies and Mermaid 12, preserving all four locales. Preserve gateway authentication, feature gates and release safeguards.
- EKS member onboarding: the member cluster guide is now two owner commands — an Access Entry for the registered member read role and a cluster-scoped `AmazonEKSViewPolicy` association — with no Kubernetes group, kubeconfig, kubectl or RBAC step; View never reads Kubernetes Secrets, and the guide tells owners to remove any existing `AmazonEKSAdminViewPolicy`. Because View cannot list nodes, member node lists come from read-only EC2/node-group APIs through the same role and are labeled as an EC2/node-group view (no kubelet status, instance-type capacity as allocatable, no Fargate nodes); their Ready count shows as "EC2 running N · Ready unknown" and they are left out of reserved-% figures; a failed node read no longer marks the whole cluster unreachable. When an administrator opens EKS, member clusters whose Access Entry is verified are listed first in an "Access Entry verified" callout with a one-click [조회 등록] button; nothing is registered until the administrator clicks it (an app registration record only; AWSops creates no AWS or Kubernetes permissions), and an unregistered cluster stays unregistered. In diagnosis, the Kubernetes map and the node drilldown, EC2/node-group nodes read as "EC2 running · Ready unknown" with Pressure, Allocatable and Reserved shown as unknown instead of as unhealthy or fully allocatable. Entries created from the earlier guide keep working.
- Bedrock models: chat answers with OpenAI GPT-6 Luna (without explicit Bedrock cache points, which GPT models reject); Explore "AI generate" writes queries with GPT-6.1 Terra and retries on Claude Sonnet 5.5 when Terra fails or its draft fails validation; primary, corrections and fallback share a 55-second request deadline with SDK cancellation; AI Diagnosis, routing, synthesis and the background workers move to Claude Sonnet 5.5, Opus 5.5 (AI Diagnosis Deep tier option) and Haiku 5.5. These models reject `temperature`, so requests no longer send it. Haiku calls and Sonnet calls with fixed output caps run without extended thinking so existing budgets still fit; Opus 5.5, which always thinks, gets extra output headroom for Deep report sections and invariant proposals. The web task now always holds a grant for its direct query-generation and assistant models (Terra, Sonnet 5.5, Haiku 5.5), so "AI generate" and the product-help assistant no longer fail with AccessDenied when hybrid routing is off; the chat runtime role additionally allows GPT-6 Luna. With `model_provider = mixed`, the Terraform variable `agentcore_chat_model_id = "global.anthropic.claude-sonnet-5-5"` rolls chat back to Sonnet 5.5 on every provisioning run, and the chat footer shows a model only when the answer carries its model provenance.
Expand Down Expand Up @@ -709,6 +710,7 @@ First release of the **v2 line** (versioned independently from the v1 1.x line,

### Changed

- 전체 트레이스 집계 기반 서비스 맵: 표준 OTel exporter 테이블을 쓰는 ClickHouse 트레이스 원본은 최신 스팬 1,000개를 이어 붙이는 대신, 제한된 읽기 전용 집계 쿼리(2개, 테이블에 span link가 있으면 1개 추가)로 1시간 구간 전체의 서비스 호출·DB 접근·워크로드·메시징을 셉니다. 호출량이 적은 연결이나 DB가 맵에서 빠지지 않고, 부모 스팬이 표본 밖에 있던 호출도 끊긴 스팬으로 표시되지 않습니다. 집계 쿼리가 실패하면 그 수집은 최신 스팬 표본으로 대신 읽고 부분 수집으로 표시합니다. 사용자 정의·생성된 ClickHouse 쿼리와 Tempo는 기존 스팬 표본 방식을 유지합니다. 노드 상한을 적용할 때도 남기는 DB·큐·워크로드는 호출하는 서비스와 함께 남깁니다. Prometheus/Mimir 서비스 그래프 지표는 서비스 간 호출만 더하며, Tempo가 DB·큐·계측되지 않은 상대와의 연결로 표시한 행은 더 이상 같은 이름의 서비스로 그려지지 않습니다. 새 지표 쿼리를 쓰려면 데이터소스 그래프 카탈로그(`datasource_index`)를 다시 만들어야 합니다.
- 웹 프레임워크·런타임 최신화: Next.js 16.4.5, React 19.3.1, Node 26.13.0으로 인증·소유권 검사·standalone 배포를 유지하고 요청 본문 제한을 Next.js proxy 규약으로 옮깁니다. 호환성 버전 고정과 함께 JavaScript/Python 의존성·AgentCore SDK, Terraform 1.17.1·provider 잠금파일, Python 3.14 Lambda·컨테이너 런타임을 갱신합니다. 문서 가이드는 Node 26에서 빌드·배포하며 문서 사이트의 보안 의존성과 Mermaid 12를 갱신하고 4개 언어를 유지합니다. Gateway 인증·기능 게이트·릴리스 보호 장치는 유지합니다.
- EKS 멤버 온보딩: 멤버 클러스터 가이드가 소유자 명령 두 개(등록된 멤버 읽기 역할의 Access Entry 생성, 클러스터 범위 `AmazonEKSViewPolicy` 연결)로 줄었으며 Kubernetes 그룹·kubeconfig·kubectl·RBAC 단계가 없습니다. View는 Kubernetes Secrets를 읽지 않으며, 가이드는 기존 `AmazonEKSAdminViewPolicy` 연결을 제거하도록 안내합니다. View로는 노드를 조회할 수 없으므로 멤버 노드 목록은 같은 역할로 읽기 전용 EC2/노드그룹 API에서 가져와 EC2/노드그룹 기준으로 표시합니다(kubelet 상태 없음, allocatable은 인스턴스 타입 용량, Fargate 노드 제외). 이 노드의 Ready 수는 "EC2 running N · Ready unknown"으로 표시되며 예약 비율 계산에서 제외됩니다. 노드 조회만 실패해도 클러스터 전체가 조회 불가로 표시되지 않습니다. 관리자가 EKS 화면을 열면 Access Entry가 확인된 멤버 클러스터가 "Access Entry 확인됨" 안내 영역에 먼저 표시되고 [조회 등록] 버튼 한 번으로 등록할 수 있으며, 관리자가 누르기 전에는 등록되지 않습니다(앱 등록 기록만 저장, AWSops는 AWS·Kubernetes 권한을 만들지 않음). 해제한 클러스터는 해제 상태로 유지됩니다. 진단 표·Kubernetes 맵·노드 상세에서도 EC2/노드그룹 노드는 "EC2 running · Ready unknown"으로 표시되며 Pressure·Allocatable·Reserved는 비정상이나 전량 할당 대신 알 수 없음으로 표시됩니다. 이전 가이드로 만든 항목도 그대로 동작합니다.
- Bedrock 모델: 채팅은 OpenAI GPT-6 Luna로 답합니다(GPT 모델이 거부하는 명시적 Bedrock 캐시 포인트는 끔). Explore "AI로 생성"은 GPT-6.1 Terra로 쿼리를 만들고, Terra 호출이 실패하거나 초안이 검증에서 거부되면 Claude Sonnet 5.5로 다시 시도합니다. 기본 모델·수정·폴백은 하나의 55초 요청 제한 시간과 SDK 취소 신호를 공유합니다. AI 진단, 라우팅, 합성, 백그라운드 워커는 Claude Sonnet 5.5, Opus 5.5(AI 진단 Deep 단계 선택), Haiku 5.5로 바뀝니다. 이 모델들은 `temperature`를 거부하므로 요청에서 더 이상 보내지 않습니다. Haiku 호출과 출력 상한이 고정된 Sonnet 호출은 기존 상한이 유지되도록 확장 사고 없이 실행하고, 항상 사고하는 Opus 5.5는 Deep 리포트 섹션과 불변식 제안에 출력 여유분을 더 받습니다. 웹 태스크는 직접 호출하는 쿼리 생성·도움말 모델(Terra, Sonnet 5.5, Haiku 5.5) 권한을 항상 가지므로, 하이브리드 라우팅이 꺼져 있어도 "AI로 생성"과 제품 도움말이 AccessDenied로 실패하지 않습니다. 채팅 런타임 역할은 GPT-6 Luna도 허용합니다. `model_provider = mixed`일 때 Terraform 변수 `agentcore_chat_model_id = "global.anthropic.claude-sonnet-5-5"`로 채팅을 Sonnet 5.5로 되돌리며 매 프로비저닝마다 유지되고, 채팅 하단의 모델 표시는 답변에 모델 출처가 있을 때만 나타납니다.
Expand Down
31 changes: 31 additions & 0 deletions docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -544,6 +544,35 @@ runtime payloads for compatibility with older or malformed responses.
| `readStatus`, `readReason`, `readTruncated` | API read availability/coverage, independent of collector status: `ok`, `partial` (`row_limit`), or `unavailable` (`busy`/`timeout`/`query_failed`). |
| `sources[].scope/capturedAtMs/lastSuccessAtMs`, `publishedSources[]` | Current/saved source status, scope and reasons, plus optional capture/sweep clocks and saved provenance. Missing status is explicitly unknown; absent clocks are not fabricated. |

### Trace graph sources

A ClickHouse datasource whose registry query is the catalog's exporter-schema `otel_v1` template
(exactly the bare exporter columns; generated or aliased templates are excluded), or the
unregistered default, is read as whole-window aggregates of the same table, not as the newest
spans. Two bounded read-only queries return service/kind/status attribute groups with span counts
and parent→child service pairs; a third returns span-link pairs when the table has `Links`
columns. Each is limited to 1,000 rows and to the connector's execution budget. If an aggregate
query fails (for example the join exceeds that budget), the same table is read with the bounded
newest-span reader instead and the source is `partial` with `incomplete_collection`. A malformed
response envelope fails the read; malformed individual rows are skipped as `malformed_rows`, a
saturated limit adds `cap_reached`, rows outside the window add `incomplete_collection`, and an
unproven empty result adds `empty_not_confirmed` (a partial read that may publish nodes without
edges). Without those reasons, node and edge `spanCount` count the window's spans, and
source-counted pairs produce no `orphanSpans`. A child whose parent started before the window is
not counted as a pair and is not disclosed. Grouping keeps only EC2 instance IDs and ARNs from the
instance claim attributes, plus a fixed marker for any other `cloud.resource_id` (which still
vetoes binding). Generated or custom templates, Tempo and other sources keep span sampling, and a
graph mixing them sums both kinds of count.

Publication keeps at most 200 nodes and 500 edges (`nodeDrops`/`edgeDrops`). Nodes are selected
from the heaviest edges first, both endpoints together, so a kept database, queue or workload
always keeps its caller; remaining capacity goes to other nodes by span and metric volume.

Service-graph metrics contribute service→service `calls` only. Rows whose Tempo
`connection_type` is `database`, `messaging_system` or `virtual_node` name a database, queue or
uninstrumented peer rather than a service and are not drawn; databases and queues come from trace
spans with their host-qualified identity.

### Trace edge instance observations

Trace `queries` edges (service → `db`) may carry three additive, optional `meta` fields built by
Expand All @@ -556,6 +585,8 @@ no bound observation was recorded, not that no instance queried the database.
| `instance_observations_omitted` | Count of further distinct pairs dropped by the 200-pair cap. |
| `instance_observations_unbound` | Count of spans whose EC2 claim could not be bound: missing or invalid account/region/clock, or no unique inventory EC2 instance and RDS instance endpoint in the same account and region. |

For aggregate sources, `observation_count` and `instance_observations_unbound` count the spans behind each aggregate row, and `correlation_id` names one sample span of the row.

These are sampled telemetry claims bound to inventory, not authority: a pair shows that the
sampled spans named that instance and endpoint within the trace window. It does not prove
current connectivity, credentials or complete coverage of instances querying the database.
Expand Down
16 changes: 16 additions & 0 deletions docs/runbooks/graph-read-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -220,6 +220,22 @@ Oversized valid Tempo children keep a bounded structured OTLP projection and can

The shared query normalizer carries collection status into Explore. Marked partial, unknown or failed empty responses show an uncertainty/failure note instead of an ordinary empty-result claim; useful rows remain visible with the same disclosure. Scalar format failures remain distinct from empty responses. Non-boolean truncation metadata is unverified, never silently interpreted as complete output.

### Whole-window ClickHouse aggregates

The ClickHouse adapter for the catalog's exporter-schema template reads node groups,
parent→child pairs and (when present) span links as whole-window aggregates; see
[trace graph sources](../api-reference.md#trace-graph-sources). The aggregates form one source
read. A failed aggregate query (including one that exceeds the connector's `max_execution_time`)
falls back to the bounded newest-span reader for that rebuild and is disclosed as
`incomplete_collection`, so a busy table degrades to sampling instead of retaining a frozen graph;
a malformed response envelope fails the read. Nodes therefore never publish from a partial set of
aggregates. Malformed individual rows are skipped as partial evidence, and each aggregate needs its
own empty proof: confirmed nodes with an unproven-empty pair query publish as `partial` with
`empty_not_confirmed`. Row limits disclose `cap_reached` like other bounded sources. The join sides
project only the sorted identity attributes. Node-cap selection keeps edge endpoints together.
The adapter and builder contracts run without PostgreSQL:
`cd web && npx vitest run lib/trace-source.test.ts lib/trace-graph.test.ts lib/graph-store-trace.test.ts lib/graph-sources.test.ts`.

## Rebuild capacity

Flow and infra input allow 8192 rows within the same bounded read envelope. The 64KiB-per-row and 8MiB projected-data/identifier limits still apply, as do the
Expand Down
7 changes: 5 additions & 2 deletions scripts/v2/workers/graph_catalog.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@

# v3: preserve span operation/status/links and metric identity scopes. Rebuild cached queries so
# source adapters receive metadata before aggregation, and both time bounds share one anchor.
CATALOG_VERSION = "v3"
# v4: service-graph PromQL keeps connection_type; rebuild so indexed instances pick it up.
CATALOG_VERSION = "v4"

# The OTel ClickHouse exporter's default `otel_traces` column shape. A table matching this column
# SET (regardless of its actual name) is treated as the span source.
Expand Down Expand Up @@ -121,7 +122,9 @@ def _servicegraph_calls(kind, schema):
if isinstance(schema, dict):
metrics = {m for m in (schema.get("metrics") or []) if isinstance(m, str)}
if _SERVICEGRAPH_METRIC in metrics:
labels = ",".join(("client", "server") + _IDENTITY_LABELS)
# connection_type separates database/messaging/virtual-node rows from service calls; dropping
# it would merge a db.name server label into a same-named service node.
labels = ",".join(("client", "server", "connection_type") + _IDENTITY_LABELS)
expr = f"sum by ({labels}) (increase({_SERVICEGRAPH_METRIC}[{{window}}m]))"
return {"query_key": "servicegraph_calls", "status": "ready",
"query": {"tool": tool, "mapper": "servicegraph_v1", "args_template": {"query": expr}},
Expand Down
2 changes: 1 addition & 1 deletion scripts/v2/workers/test_graph_catalog.py
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ def test_grouping_preserves_every_identity_label_recognized_by_the_web_mapper(se
assert aliases, "identity label aliases must be explicit for the catalog/mapper contract"
suffixes = set(re.findall(r"'([a-z_]+)'", aliases.group(1)))
for kind, metric, endpoints in [
("prometheus", "traces_service_graph_request_total", ("client", "server")),
("prometheus", "traces_service_graph_request_total", ("client", "server", "connection_type")),
("mimir", "istio_requests_total", ("source_workload", "destination_workload")),
]:
query = gc.build_graph_queries(kind, {"metrics": [metric]})[0]["query"]["args_template"]["query"]
Expand Down
Loading
Loading