Prerequisites

• Search the current open issues

What are you trying to do that currently feels hard or impossible?

Currently, there's no way to correlate a SQL query back to the LLM tool invocation, client, or distributed trace that triggered it. The observability chain breaks at the Toolbox server boundary.

Suggested Solution(s)

SQLCommenter appends structured key-value comments to SQL statements, propagating application context (traceparent, client.identity, tool.name etc) into database query logs. Gated on --telemetry-otlp / --telemetry-gcp and hence zero overhead when off.

/*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-abc123-def456-01*/ SELECT * FROM users;

1. Parse _meta["dev.mcp-toolbox/telemetry"]: merge with existing trace context extraction (single json.Unmarshal), store client attrs in request context.
2. New internal/sources/sqlcommenter/ package: AppendComment(ctx, statement, dbSystemName) collects attributes from context and appends as SQL comment.
3. Wire into postgres.go RunSQL(): one line: statement = sqlcommenter.AppendComment(ctx, statement, "postgresql")

Attributes: traceparent, server, client, client.model, client.user.id, client.agent.id, tool.name, db.system.name

Alternatives Considered

No response

Additional Details

For the scope of this issue and v1 enablement of SQL Commenter, the server takes in fields from

1. client: via _meta["dev.mcp-toolbox/telemetry"], precisely client name, version, model, user id and agent id
2. server: extracts tool.name, and server name/version, active parent trace
   and pass them to the AppendComment function to extend SQL query with the comment

Future scope of work:

• Gatekeep with specific sql_commenter_enable flag to enable sqlCommenter appends.
• Export the same telemetry attributes in server spans as well.