feat(metrics): add optional id and properties fields to metrics output#5983
Open
not4s wants to merge 8 commits into
Open
feat(metrics): add optional id and properties fields to metrics output#5983not4s wants to merge 8 commits into
not4s wants to merge 8 commits into
Conversation
not4s
force-pushed
the
feat/metrics-properties
branch
from
8cdc240 to
e5233da
Compare
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #5983 +/- ##
==========================================
+ Coverage 82.97% 83.00% +0.02%
==========================================
Files 277 277
Lines 30128 30204 +76
==========================================
+ Hits 25000 25071 +71
- Misses 5128 5133 +5
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Allow operators to attach custom key-value properties to the metrics config, via PUT /metrics or the boot config file. When set, the properties are emitted under a top-level "properties" field on every metrics line; when omitted, output is unchanged for backwards compatibility. Properties are set once at config time (pre-boot) and fixed for the VM's lifetime, matching how metrics are configured today. They are bounded (max 10 keys, 64-byte keys, 512-byte values) to keep metrics lines from bloating. This lets operators tag a microVM's metrics with their own context, such as the customer or bundle running in it. Signed-off-by: Jay Chung <jaehoc@amazon.com>
The metrics-line validator builds a strict jsonschema (additionalProperties: False), so the optional top-level "properties" map emitted by configurable metrics properties would be rejected as an unexpected key. Register "properties" in the schema as an optional object with string values, without marking it required. Real metrics stay strictly validated; the key is tolerated when present and ignored when absent. Signed-off-by: Jay Chung <jaehoc@amazon.com>
Add the optional "properties" field to the Metrics definition in the OpenAPI spec, typed as an object with string values, and document the feature in docs/metrics.md: how to set it (PUT /metrics or the config file's metrics block, not --metrics-path), the size limits, and a before/after example of the emitted line. Signed-off-by: Jay Chung <jaehoc@amazon.com>
not4s
force-pushed
the
feat/metrics-properties
branch
from
e5233da to
aaebe7b
Compare
Operators shipping metrics from many microVMs to a shared sink (e.g. one CloudWatch log group) cannot tell which VM a line came from, since lines carry no identifier. Add an opt-in `emit_id` field to the metrics configuration that emits the microVM instance id (the jailer `--id`) under a top-level `id` field on every metrics line. Keep it independent of the custom `properties` map: either can be enabled without the other. Both default to off, so the line shape is unchanged for existing consumers. Signed-off-by: Jay Chung <jaehoc@amazon.com>
Tolerate the top-level `id` field as an optional string in the metrics schema validator, mirroring the existing `properties` tolerance, while keeping every real metric strictly validated. Signed-off-by: Jay Chung <jaehoc@amazon.com>
Describe the opt-in `emit_id` field and the top-level `id` it produces, and document it in the swagger Metrics definition. Restructure the docs so `id` and `properties` are presented as independent optional fields. Signed-off-by: Jay Chung <jaehoc@amazon.com>
Record the two new opt-in metrics fields, `emit_id` and `properties`, under the Unreleased section as a single entry for the PR. Signed-off-by: Jay Chung <jaehoc@amazon.com>
Cover the emitted metrics line shape, which the unit tests cannot reach since they exercise the serializer in isolation rather than a running microVM. Assert each combination of the two opt-in fields: neither set, `emit_id` alone, `properties` alone, and both together, checking that the `id` and `properties` keys appear (or not) and carry the configured values. Signed-off-by: Jay Chung <jaehoc@amazon.com>
not4s
force-pushed
the
feat/metrics-properties
branch
from
aaebe7b to
dee5388
Compare
not4s
added
the
Status: Awaiting review
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changes
Add two optional, independent fields to the metrics configuration (
PUT /metricsand themetricsblock of a config file), each emitted as a top-level key on every metrics line and each off by default:emit_id(boolean): emits the microVM instance id (the value passed to the jailer--id) under a top-levelidfield.properties(map of string to string): emits operator-defined key-value pairs under a top-levelpropertiesfield. Bounded to at most 10 entries, keys up to 64 bytes, and values up to 512 bytes.When neither is configured, the metrics line is byte-for-byte unchanged, so existing consumers are unaffected.
Example line with both enabled:
{"utc_timestamp_ms": 1739000000000, "id": "my-instance", "properties": {"bundle_id": "fn-abc", "customer_id": "1234"}, "api_server": {"...": 0}}Reason
Operators that collect metrics from many microVMs into a single destination (for example, a log agent that globs every VM's metrics file into one log stream) cannot tell which microVM a given line came from, because the lines carry no identifier. The original feature request asked for arbitrary key-value tagging to attribute lines to a VM; subsequent discussion clarified that the primary need is simply a stable, authoritative identifier, with operator tags as an enrichment.
Design decisions
id as a separate top-level field, not a key inside properties. An earlier idea was to auto-populate the instance id inside the properties map. A separate id field was chosen instead, for several reasons:
Two independent opt-in switches: Both default to off so the default line shape is unchanged (backwards compatibility). emit_id is a boolean toggle modeled on the existing LoggerConfig show_level / show_log_origin toggles.
properties size limits: Capped to keep metrics lines from growing without bound. The limits (10 / 64 / 512) are conservative defaults that can be raised later without breaking compatibility.
No CLI flag for properties: Structured data is supplied through the API or a config file, not the command line. This matches convention that CLI arguments are scalars, paths, and booleans, with structured input provided by file (as MMDS content already does). --metrics-path continues to configure only the path.
Omitted when unset, not emitted empty: When a field is not configured its key is absent entirely.
Snapshot behavior unchanged: Metrics configuration is not part of the snapshot and is reconfigured on a restored microVM; this change adds nothing to the snapshot surface.
License Acceptance
By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache 2.0 license. For more information on following Developer
Certificate of Origin and signing off your commits, please check
CONTRIBUTING.md.PR Checklist
tools/devtool checkbuild --allto verify that the PR passesbuild checks on all supported architectures.
tools/devtool checkstyleto verify that the PR passes theautomated style checks.
how they are solving the problem in a clear and encompassing way.
in the PR.
CHANGELOG.md.Runbook for Firecracker API changes.
integration tests.
TODO.rust-vmm.