feat(bigquery): add default_attributes config to BigQueryAgentAnalyticsPlugin

[andrewrfitz]

Summary

This PR adds a new default_attributes configuration option to BigQueryLoggerConfig that allows users to inject static key-value pairs into every logged event's attributes field.

Use case: When deploying ADK-based services, it's useful to include deployment metadata (service version, environment, commit SHA, etc.) in analytics events for filtering and debugging in BigQuery.

Closes #4212

Changes

• Added default_attributes: Optional[dict[str, Any]] = None to BigQueryLoggerConfig
• Modified _log_event() to merge default attributes with event-specific attributes
• Event-specific attributes override defaults when there are key conflicts
• Fully backward compatible (defaults to None)

Example Usage

config = BigQueryLoggerConfig(
    default_attributes={
        "service_version": "1.2.3",
        "environment": "production",
        "commit_sha": "abc123",
    }
)
plugin = BigQueryAgentAnalyticsPlugin(
    project_id="my-project",
    dataset_id="adk_analytics", 
    config=config,
)

All events logged by this plugin will now include these attributes in the attributes JSON column.

Testing Plan

Unit Tests

Added 3 new unit tests:

• test_default_attributes_included_in_events - verifies default attributes appear in logged events
• test_default_attributes_overridden_by_event_attributes - verifies event-specific attributes take precedence
• test_default_attributes_none_does_not_affect_events - verifies backward compatibility

Test Results

pytest tests/unittests/plugins/test_bigquery_agent_analytics_plugin.py -v
======================== 46 passed, 1 warning in 8.76s =========================

All existing tests continue to pass.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @andrewrfitz, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the BigQuery analytics plugin by providing a mechanism to automatically enrich all logged events with predefined, static metadata. This capability simplifies the process of adding consistent contextual information, such as deployment details, to analytics data, which is invaluable for subsequent filtering, analysis, and debugging within BigQuery without requiring manual inclusion in every event.

Highlights

• New Configuration Option: Introduced a default_attributes configuration option to BigQueryLoggerConfig.
• Static Metadata Injection: This new option allows users to inject static key-value pairs into every logged event's attributes field, useful for deployment metadata like service version or environment.
• Attribute Merging Logic: Implemented logic to merge default_attributes with event-specific attributes, ensuring that event-specific attributes take precedence in case of key conflicts.
• Backward Compatibility: The feature is fully backward compatible, as default_attributes defaults to None.
• Unit Test Coverage: Added three new unit tests to verify the inclusion of default attributes, the override behavior by event-specific attributes, and proper functionality when default_attributes is None.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[adk-bot]

Response from ADK Triaging Agent

Hello @andrewrfitz, thank you for your contribution!

Before we can merge this PR, could you please:

• Sign our Contributor License Agreement (CLA) at https://cla.developers.google.com/.
• Create a GitHub issue for this feature and link it in the PR description.

This will help us to track the work and review your PR more efficiently. Thanks!

[gemini-code-assist]

Code Review

This pull request introduces a default_attributes configuration option to the BigQueryAgentAnalyticsPlugin, allowing for the injection of static key-value pairs into every logged event. This is a valuable feature for enriching analytics data with deployment metadata. The implementation correctly merges default and event-specific attributes, prioritizing the latter in case of conflicts. The changes are well-documented, and the accompanying unit tests are comprehensive, covering all key aspects of the new functionality including attribute inclusion, overriding, and backward compatibility. The code quality is high, and I have no concerns with the proposed changes.

[andrewrfitz]

@ryanaiagent I've followed the steps for CLA as a 'Corporate signer', I'm in the google group and signed the CLA, but it's still failing the git action. Can you provide an guidance here?

[ryanaiagent]

Hi @andrewrfitz , try https://cla.developers.google.com/ .

[andrewrfitz]

Hi @andrewrfitz , try https://cla.developers.google.com/ .

99be03e Author: @andrewrfitz <and******tz​@bilt.com>

I've signed the CLA, and this email is in the google group associated, but the check is still failing. Not sure if there's anything else I can try?

[ryanaiagent]

Hi @andrewrfitz , maybe try the following the steps mentioned in the link below for googlers and TVC.

[andrewrfitz]

Hi @andrewrfitz , maybe try the following the steps mentioned in the link below for googlers and TVC.

I've tried everything, still not working :/

My public email is in our corporate CLA, its the same one attached to my commit

[andrewrfitz]

@ryanaiagent finally got it working! ready for review now, thank you for your help 🙏

[ryanaiagent]

Hi @Jacksunwei , can you please review this.

[caohy1988]

Recommended Solution: Use custom_tags

Technically, the existing custom_tags configuration already solves the core problem: injecting static metadata into every analytics event.

Instead of waiting for a new default_attributes feature, you can configure your BigQueryLoggerConfig right now like this:

config = BigQueryLoggerConfig(
    # ... other config ...
    custom_tags={
        "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"),
    }
)

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_tags and the proposed default_attributes feature is the JSON path in BigQuery. Your metadata will be nested under a custom_tags key within the attributes JSON column (rather than being at the root).

You can query it easily using JSON functions:

Feature	Query Syntax
default_attributes (Proposed)	WHERE JSON_VALUE(attributes, '$.environment') = 'production'
custom_tags (Existing)	WHERE JSON_VALUE(attributes, '$.custom_tags.environment') = 'production'

Example queries:

-- Query events by environment
SELECT *
FROM `your_project.your_dataset.agent_events_v2`
WHERE JSON_VALUE(attributes, '$.custom_tags.environment') = 'production'

-- Debug specific commits
SELECT *
FROM `your_project.your_dataset.agent_events_v2`
WHERE JSON_VALUE(attributes, '$.custom_tags.commit_sha') = 'abc123';

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_tags keeps 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_tags functionality.

[andrewrfitz]

Recommended Solution: Use custom_tags

Technically, the existing custom_tags configuration already solves the core problem: injecting static metadata into every analytics event.

Instead of waiting for a new default_attributes feature, you can configure your BigQueryLoggerConfig right now like this:

config = BigQueryLoggerConfig(
    # ... other config ...
    custom_tags={
        "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"),
    }
)

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_tags and the proposed default_attributes feature is the JSON path in BigQuery. Your metadata will be nested under a custom_tags key within the attributes JSON column (rather than being at the root).

You can query it easily using JSON functions:

Feature Query Syntax
default_attributes (Proposed) WHERE JSON_VALUE(attributes, '$.environment') = 'production'
custom_tags (Existing) WHERE JSON_VALUE(attributes, '$.custom_tags.environment') = 'production'
Example queries:

-- Query events by environment
SELECT *
FROM `your_project.your_dataset.agent_events_v2`
WHERE JSON_VALUE(attributes, '$.custom_tags.environment') = 'production'

-- Debug specific commits
SELECT *
FROM `your_project.your_dataset.agent_events_v2`
WHERE JSON_VALUE(attributes, '$.custom_tags.commit_sha') = 'abc123';

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_tags keeps 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_tags functionality.

Thanks for the detailed response @caohy1988! You're right that custom_tags covers the static deployment metadata use case I described in this PR.

However, my broader goal is actually per-session dynamic metadata in BigQuery events, not just static deployment tags. For example, attaching session-specific context to every event row so I can filter/debug in BigQuery at the session level.

custom_tags can't solve this since it's set once at plugin construction time and stamped identically on every event across all sessions.

Thoughts on this?