wehub-resource-sync
e04ed9c211
CF: Deploy Dev Docs / deploy (push) Has been cancelled
Sync Labels / build (push) Has been cancelled
tests / unit tests (macos-latest) (push) Has been cancelled
tests / unit tests (windows-latest) (push) Has been cancelled
tests / unit tests (ubuntu-latest) (push) Has been cancelled
92 lines
5.3 KiB
Markdown
92 lines
5.3 KiB
Markdown
---
|
|
title: "SQL Commenter"
|
|
type: docs
|
|
weight: 10
|
|
description: >
|
|
Propagate application context into database query logs by prepending SQLCommenter-format comments to executed SQL statements.
|
|
---
|
|
|
|
[SQLCommenter](https://google.github.io/sqlcommenter/) is an open-source
|
|
convention that propagates application context into the database by prepending a
|
|
structured comment to every SQL statement before it is executed. The comment is
|
|
stripped before query planning, so it has no effect on results — but it shows up
|
|
verbatim in database query logs and slow-query logs, letting you correlate a
|
|
specific SQL statement back to the MCP client, LLM tool invocation, model, user,
|
|
agent, and distributed trace that triggered it.
|
|
|
|
This closes the observability gap between the application-level traces emitted by
|
|
Toolbox and the database-level logs emitted by your underlying database engine.
|
|
|
|
## Enabling SQL Commenter
|
|
|
|
SQL Commenter is opt-in and disabled by default. Enable it on a per-source basis by setting the `sqlCommenter` field to `true` in a source's configuration file:
|
|
|
|
```yaml
|
|
sources:
|
|
- name: my-pg-source
|
|
type: postgres
|
|
# ...
|
|
sqlCommenter: true
|
|
```
|
|
|
|
If you are exporting telemetry using OpenTelemetry, the `traceparent` attribute embedded in the SQL comment will automatically be part of the same distributed trace exported by Toolbox:
|
|
|
|
```bash
|
|
./toolbox --telemetry-otlp="127.0.0.1:4553"
|
|
```
|
|
|
|
## Supported Sources
|
|
|
|
SQL Commenter is supported on the following database sources:
|
|
|
|
* `alloydb-postgres`
|
|
* `cloud-sql-postgres`
|
|
* `cloud-sql-mysql`
|
|
* `postgres`
|
|
* `mysql`
|
|
* `sqlite`
|
|
|
|
## Comment Format
|
|
|
|
When enabled, Toolbox prepends a SQLCommenter-format comment to every SQL
|
|
statement executed against a supported source. Keys are sorted alphabetically,
|
|
values are URL-encoded, and pairs are joined by commas inside a `/* … */`
|
|
block. For example:
|
|
|
|
```sql
|
|
/*client='toolbox-langchain-python%2Fv0.1.0',client.model='gemini-2.5-flash',db.system.name='postgresql',server='genai-toolbox%2F1.1.0',tool.name='search_user',traceparent='00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'*/ SELECT * FROM users WHERE id = $1;
|
|
```
|
|
|
|
## Attributes
|
|
|
|
| **Attribute** | **Source** | **Description** |
|
|
|---------------------|--------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
|
|
| `traceparent` | Active OpenTelemetry span context. | W3C Trace Context header tying the SQL statement to the distributed trace for this invocation. |
|
|
| `server` | Toolbox build (`genai-toolbox/<version>`). | Identifies the Toolbox server name and version that issued the query. |
|
|
| `tool.name` | The tool being invoked. | The tool whose execution triggered the SQL. |
|
|
| `db.system.name` | The database engine (e.g. `postgresql`, `mysql`, `sqlite`). | Identifies the database backend. |
|
|
| `client` | MCP client `params._meta["dev.mcp-toolbox/telemetry"]["client.name"]` and/or `["client.version"]` (joined by `/`). | Identifies the ADK or application that initiated the MCP request. |
|
|
| `client.model` | MCP client `params._meta["dev.mcp-toolbox/telemetry"]["client.model"]`. | The LLM model that produced the tool call. |
|
|
| `client.user.id` | MCP client `params._meta["dev.mcp-toolbox/telemetry"]["client.user.id"]`. | End-user identifier supplied by the client. |
|
|
| `client.agent.id` | MCP client `params._meta["dev.mcp-toolbox/telemetry"]["client.agent.id"]`. | Agent identifier supplied by the client. |
|
|
|
|
Client-supplied attributes (`client`, `client.model`, `client.user.id`,
|
|
`client.agent.id`) are populated from the MCP request's
|
|
`params._meta["dev.mcp-toolbox/telemetry"]` field. Attributes that are not
|
|
provided by the client or not applicable in the current context are omitted
|
|
from the comment.
|
|
|
|
## Populating Client Attributes from SDKs
|
|
|
|
Toolbox SDKs that support the `dev.mcp-toolbox/telemetry` meta field will
|
|
populate `client.*` attributes automatically. With the Python SDK, you can
|
|
attach per-tool attributes such as model name, user ID, and agent ID using
|
|
`TelemetryAttributes`. See [Per-call Telemetry Attributes](../../connect-to/toolbox-sdks/python-sdk/core/#per-call-telemetry-attributes)
|
|
for details.
|
|
|
|
{{< notice tip >}}
|
|
The comment is plain text in your database logs. To follow a slow query back to
|
|
its trace, take the `traceparent` value and search your tracing backend for the
|
|
matching trace ID (the second segment of the W3C `traceparent`).
|
|
{{< /notice >}}
|