[PR #168] [MERGED] feat(snapshot): add artifact dimension to OSS upload observability #224

New issue

Closed

opened 2026-10-29 14:21:12 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:21:12 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/168
Author: @huajq
Created: 8/13/2026
Status: ✅ Merged
Merged: 8/13/2026
Merged by: @yingdi-shan

Base: main ← Head: feat/snapshot-upload-artifact-metrics

📝 Commits (1)

ef2a15e feat(snapshot): add artifact dimension to OSS upload observability

📊 Changes

3 files changed (+154 additions, -27 deletions)

View changed files

📝 src/observability/prometheus.rs (+36 -0)
📝 src/snapshot/repository/backends/oss/client.rs (+56 -4)
📝 src/snapshot/repository/backends/oss/repository.rs (+62 -23)

📄 Description

What

Snapshot OSS upload metrics (agentenv_snapshot_oss_upload_bytes_total,
and the put_file/put_bytes series of
agentenv_snapshot_oss_operation_duration_seconds) gain an artifact
label: rootfs_layer / attached_drive_layer / memory_layer /
vm_state / manifest / record / alias.
Each completed put_file logs key, artifact, size_bytes,
elapsed_ms at info level.

Why

Upload metrics could not distinguish memory layers from disk layers, and
canceled uploads left no per-artifact trace. Slow or canceled snapshot
publishes can now be attributed to a specific artifact.

None.

Scope and non-goals

In scope: the OSS repository upload path and the shared MetricGuard.
Non-goals: no timeout/retry behavior changes; POSIX backend, ACR/regctl
path, and the download/resolver path are untouched.

Design and behavior changes

New MetricGuard::operation_artifact label variant; guards dropped
mid-flight still record status="canceled", now with the artifact.
New OssUploadArtifact enum threaded through the publish flow;
DiskImageSubject maps to rootfs/attached-drive artifact.
Removed the now-redundant debug!("uploaded managed layer to oss") (the
managed-layer key already contains the digest) and its digest parameter.

Compatibility and operations

Public API or generated protocol: N/A — no API changes.
Configuration or defaults: N/A.
Snapshot manifest, artifact layout, or storage format: N/A.
Upgrade and rollback: upload metric series gain an artifact label;
sum by (operation)-style queries remain valid. Rollback is a revert.
Host requirements, permissions, ports, or dependencies: N/A.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

make fmt                                # OK
make clippy                             # OK, workspace-wide, no warnings (Linux host)
cargo test -p agentenv --lib snapshot:: # 116 passed, 0 failed

Skipped checks and reasons:

make test-unit: covered by CI; the unit tests of the touched module were
run directly (see above).
Integration tests: require KVM/ublk hosts; this change touches no runtime
path.
services/, generated code, docs, benchmarks: not affected.

Risks and reviewer notes

The duration histogram has mixed label sets (only put_file/put_bytes
carry artifact); valid Prometheus, existing aggregations unaffected.
~4 extra info log lines per snapshot publish.
Focus: src/snapshot/repository/backends/oss/client.rs,
src/snapshot/repository/backends/oss/repository.rs,
src/observability/prometheus.rs.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
(Label threading only; no metrics-assertion harness exists — covered by
the existing snapshot test suite and clippy.)
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/168 **Author:** [@huajq](https://github.com/huajq) **Created:** 8/13/2026 **Status:** ✅ Merged **Merged:** 8/13/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `feat/snapshot-upload-artifact-metrics` --- ### 📝 Commits (1) - [`ef2a15e`](https://github.com/kvcache-ai/AgentENV/commit/ef2a15e0739615c177028448b00d22b6206686a9) feat(snapshot): add artifact dimension to OSS upload observability ### 📊 Changes **3 files changed** (+154 additions, -27 deletions) <details> <summary>View changed files</summary> 📝 `src/observability/prometheus.rs` (+36 -0) 📝 `src/snapshot/repository/backends/oss/client.rs` (+56 -4) 📝 `src/snapshot/repository/backends/oss/repository.rs` (+62 -23) </details> ### 📄 Description ## What - Snapshot OSS upload metrics (`agentenv_snapshot_oss_upload_bytes_total`, and the `put_file`/`put_bytes` series of `agentenv_snapshot_oss_operation_duration_seconds`) gain an `artifact` label: `rootfs_layer` / `attached_drive_layer` / `memory_layer` / `vm_state` / `manifest` / `record` / `alias`. - Each completed `put_file` logs `key`, `artifact`, `size_bytes`, `elapsed_ms` at info level. ## Why Upload metrics could not distinguish memory layers from disk layers, and canceled uploads left no per-artifact trace. Slow or canceled snapshot publishes can now be attributed to a specific artifact. ## Related issue None. ## Scope and non-goals In scope: the OSS repository upload path and the shared `MetricGuard`. Non-goals: no timeout/retry behavior changes; POSIX backend, ACR/regctl path, and the download/resolver path are untouched. ## Design and behavior changes - New `MetricGuard::operation_artifact` label variant; guards dropped mid-flight still record `status="canceled"`, now with the artifact. - New `OssUploadArtifact` enum threaded through the publish flow; `DiskImageSubject` maps to rootfs/attached-drive artifact. - Removed the now-redundant `debug!("uploaded managed layer to oss")` (the managed-layer key already contains the digest) and its `digest` parameter. ## Compatibility and operations - Public API or generated protocol: N/A — no API changes. - Configuration or defaults: N/A. - Snapshot manifest, artifact layout, or storage format: N/A. - Upgrade and rollback: upload metric series gain an `artifact` label; `sum by (operation)`-style queries remain valid. Rollback is a revert. - Host requirements, permissions, ports, or dependencies: N/A. ## Validation - [x] `make fmt` - [x] `make clippy` - [ ] `make test-unit` - [ ] Relevant Rust integration tests - [ ] `make -C services test` (required when `services/` changes) - [ ] Generated clients/server regenerated with the documented `make` target - [ ] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text make fmt # OK make clippy # OK, workspace-wide, no warnings (Linux host) cargo test -p agentenv --lib snapshot:: # 116 passed, 0 failed ``` Skipped checks and reasons: - `make test-unit`: covered by CI; the unit tests of the touched module were run directly (see above). - Integration tests: require KVM/ublk hosts; this change touches no runtime path. - `services/`, generated code, docs, benchmarks: not affected. ## Risks and reviewer notes - The duration histogram has mixed label sets (only `put_file`/`put_bytes` carry `artifact`); valid Prometheus, existing aggregations unaffected. - ~4 extra info log lines per snapshot publish. - Focus: `src/snapshot/repository/backends/oss/client.rs`, `src/snapshot/repository/backends/oss/repository.rs`, `src/observability/prometheus.rs`. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. (Label threading only; no metrics-assertion harness exists — covered by the existing snapshot test suite and clippy.) - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:21:12 +00:00