Repository navigation
feat: Add default_attributes config to BigQueryAgentAnalyticsPlugin for deployment metadata #4212
Description
Problem Statement
When deploying ADK-based services in production environments, there's no straightforward way to include deployment metadata (service version, environment, commit SHA, deployment ID, etc.) in BigQuery analytics events. This metadata is essential for:
- Debugging production issues - Correlating agent behavior with specific deployments
- A/B testing and rollouts - Comparing metrics across different service versions
- Environment filtering - Separating production vs staging vs development analytics
- Audit and compliance - Tracking which version of the service generated specific events
Current Workaround
Currently, users must manually inject these attributes into every event, which is:
- Error-prone (easy to forget)
- Repetitive (same metadata on every call)
- Not centralized (scattered across the codebase)
Proposed Solution
Add a default_attributes configuration option to BigQueryLoggerConfig that automatically merges static key-value pairs into every logged event's attributes field.
Example Usage
config = BigQueryLoggerConfig(
default_attributes={
"service_version": os.getenv("SERVICE_VERSION", "unknown"),
"environment": os.getenv("ENVIRONMENT", "development"),
"commit_sha": os.getenv("COMMIT_SHA", "unknown"),
"deployment_id": os.getenv("DEPLOYMENT_ID"),
}
)
plugin = BigQueryAgentAnalyticsPlugin(
project_id="my-project",
dataset_id="adk_analytics",
config=config,
)Behavior
- Default attributes are merged with event-specific attributes
- Event-specific attributes take precedence on key conflicts
- Fully backward compatible (
default_attributesdefaults toNone)
Use Case
We're building an AI concierge service using ADK and need to track which deployment version generated each analytics event. This allows us to:
- Query events by environment:
WHERE JSON_VALUE(attributes, '$.environment') = 'production' - Debug specific commits:
WHERE JSON_VALUE(attributes, '$.commit_sha') = 'abc123' - Compare version performance:
GROUP BY JSON_VALUE(attributes, '$.service_version')
Implementation
PR: #4207
Activity
caohy1988 commentedon Feb 9, 2026
Recommended Solution: Use
custom_tagsTechnically, the existing
custom_tagsconfiguration already solves the core problem: injecting static metadata into every analytics event.Instead of waiting for a new
default_attributesfeature, you can configure yourBigQueryLoggerConfigright now like this:This approach avoids waiting for a new release and keeps your deployment metadata cleanly separated from other dynamic event attributes.
Querying Metadata
The only user-facing difference between
custom_tagsand the proposeddefault_attributesfeature is the JSON path in BigQuery. Your metadata will be nested under acustom_tagskey within theattributesJSON column (rather than being at the root).You can query it easily using JSON functions:
default_attributes(Proposed)WHERE JSON_VALUE(attributes, '$.environment') = 'production'custom_tags(Existing)WHERE JSON_VALUE(attributes, '$.custom_tags.environment') = 'production'Example queries:
Recommendation
Unless you have a strict requirement for "root-level" attributes (e.g., for compatibility with existing queries or downstream pipelines that expect a flat schema), we recommend using
custom_tags.Using
custom_tagskeeps the API surface smaller and cleaner. It also neatly namespaces "deployment/environment" metadata away from "runtime/event" metadata, which is arguably a better practice anyway.We suggest closing this feature request as "Working as Intended" by leveraging the existing
custom_tagsfunctionality.klateefa commentedon Feb 11, 2026
@andrewrfitz Thank you for informing us. Please be assured that the request is under review, and we will keep you informed of any next steps. We appreciate your patience.
Thanks