OpentelemetrySqlcommenter (opentelemetry_sqlcommenter v0.1.1)
Adds OpenTelemetry trace context to SQL queries as comments.
OpentelemetrySqlcommenter is an Elixir library that automatically adds OpenTelemetry trace context to your SQL queries as comments. This enables better observability by linking database operations with distributed traces.
Note: Currently only compatible with PostgreSQL databases.
Features
- Automatically injects OpenTelemetry trace context into SQL queries
- Compatible with Ecto repositories using PostgreSQL
- Follows W3C Trace Context specification
- Minimal performance overhead
- Easy integration with existing projects
Installation
Add opentelemetry_sqlcommenter
to your list of dependencies in mix.exs
:
def deps do
[
{:opentelemetry_sqlcommenter, "~> 0.1.1"},
]
end
Usage
- In your Ecto repository, delegate the
prepare_query
function to OpentelemetrySqlcommenter:
defmodule YourApp.Repo do
use Ecto.Repo,
otp_app: :your_app,
adapter: Ecto.Adapters.Postgres
defdelegate prepare_query(operation, query, opts), to: OpentelemetrySqlcommenter
end
- That's it! Your SQL queries will now include trace context as comments:
SELECT u1."id", u1."email" FROM "user_token"
AS u0 INNER JOIN "user" AS u1 ON u1."id" = u0."user_id"
WHERE ((u0."token" = $1) AND (u0."context" = $2)) AND
(u0."inserted_at" > $3::timestamp + (-(60)::numeric * interval '1 day'))
/*traceparent='00-6b6bcfabaea5ef9890481e9b0c18efac-4deda0f3c249b6c7-01'*/
Configuration
No additional configuration is needed if you already have OpenTelemetry set up in your application.
How It Works
The library:
- Intercepts queries before they're sent to the database
- Checks for active OpenTelemetry trace context
- If present, adds the trace context as a SQL comment
- Preserves all existing query options
Important Disclaimer
⚠️ Impact on Query Performance
This library disables prepared statements and query caching by setting
prepare: :unnamed
for all queries. This is necessary because:
- SQL comments make each query unique, even if the underlying SQL is identical
- Prepared statements and caching rely on query text matching exactly
- Adding trace context makes each query instance unique, defeating the purpose of preparation and caching
Performance Implications
- Prepared Statements: Normally, Postgres can prepare and cache query execution plans. With this library, each query is treated as new, requiring a new execution plan.
When to Use
Use this library when:
- Trace context in SQL logs is more important than maximum query performance
- You're debugging or need detailed observability
- Your application's performance isn't critically dependent on prepared statements
Consider disabling it in performance-critical environments or creating a configuration option to toggle it based on your needs.
Alternative Approaches
If you need both tracing and prepared statements, consider:
- Using separate logging mechanisms for trace context
- Implementing selective tracing for specific queries only
- Using database-specific audit logging features
Related Links
Adds OpenTelemetry trace context to SQL queries as comments.
This module is designed to be used with Ecto repositories to automatically inject OpenTelemetry trace information into SQL queries. It adds a SQL comment containing the W3C trace context (traceparent) to each query, enabling correlation between database operations and distributed traces.
Usage
In your Ecto repository, add:
defmodule YourApp.Repo do
use Ecto.Repo,
otp_app: :your_app,
adapter: Ecto.Adapters.Postgres
defdelegate prepare_query(operation, query, opts), to: OpentelemetrySqlcommenter
end
Format
The module adds SQL comments in the following format:
YOUR QUERY/*traceparent='00-trace_id-span_id-flags'*/
Summary
Functions
Prepares a query by adding OpenTelemetry trace context as a SQL comment for any active span.
Prepares a query by adding OpenTelemetry trace context as a SQL comment, but only for sampled traces.
Functions
Prepares a query by adding OpenTelemetry trace context as a SQL comment for any active span.
Similar to prepare_query_sampled/3
but adds trace context for all traces regardless of sampling status.
Designed to be used with defdelegate
in your Ecto repository when you want to track all queries.
Setup
defmodule MyApp.Repo do
use Ecto.Repo,
otp_app: :my_app,
adapter: Ecto.Adapters.Postgres
defdelegate prepare_query(operation, query, opts), to: OpentelemetrySqlcommenter
end
Parameters
_operation
- The type of operation (unused, maintained for Ecto compatibility)query
- The SQL query stringopts
- Query options keyword list
Returns
{modified_query, modified_opts}
- Tuple containing the query and modified options with trace context{query, opts}
- Original query and options if no active sampled trace is present
Note: This function disables prepared statements by setting prepare: :unnamed
when adding trace context.
Prepares a query by adding OpenTelemetry trace context as a SQL comment, but only for sampled traces.
This function is designed to be used with defdelegate
in your Ecto repository to automatically
add trace context to all database queries when sampling is enabled (trace_flags = 1).
Setup
defmodule MyApp.Repo do
use Ecto.Repo,
otp_app: :my_app,
adapter: Ecto.Adapters.Postgres
defdelegate prepare_query(operation, query, opts), to: OpentelemetrySqlcommenter, as: :prepare_query_sampled
end
Parameters
_operation
- The type of operation (unused, maintained for Ecto compatibility)query
- The SQL query stringopts
- Query options keyword list
Returns
{modified_query, modified_opts}
- Tuple containing the query and modified options with trace context{query, opts}
- Original query and options if no active trace is present
Note: This function disables prepared statements by setting prepare: :unnamed
when adding trace context.