Events & Logging
Relevant source files
The following files were used as context for generating this wiki page:
The Events and Logging system in dbt-adapters is responsible for communicating internal dbt structures into a consumable interface. This system transforms internal operations—such as database connections, SQL execution, and cache management—into standardized event objects that can be logged, streamed, or printed.
The module is built upon protobuf definitions, providing a clearly defined interface for event consumption. It uses Python classes compiled from these definitions to ensure type safety and consistency across different database adapters.
Sources: dbt-adapters/src/dbt/adapters/events/README.md:1-5, dbt-adapters/src/dbt/adapters/events/types.py:1-10
Architecture and Components
The architecture relies on a structured event flow where every significant action in the adapter layer triggers a "fire_event" call.
Event Processing Flow
When an event is fired, it is processed through defined types that represent the exhaustive list of activities within dbt. Nearly everything processed via fire_event is logged to the file system, regardless of whether debug flags are enabled. However, high-volume events (like cache events) may require specific flags to avoid performance degradation.
The diagram shows how internal actions are transformed into structured events and distributed to various outputs.
Sources: dbt-adapters/src/dbt/adapters/events/README.md:7-14, dbt-adapters/src/dbt/adapters/events/logging.py:1-15
Adapter Logging Integration
Adapter maintainers integrate with the system using the AdapterLogger. This class provides a bridge for existing log messages to use the v1.0 event system by wrapping logs with specific adapter metadata.
from dbt.adapters.events.logging import AdapterLogger
logger = AdapterLogger("Snowflake")
logger.debug("Executing query", query_id="123")
Sources: dbt-adapters/src/dbt/adapters/events/README.md:38-48, dbt-adapters/src/dbt/adapters/events/logging.py:17-25
Event Types and Classifications
Events are categorized by their functional area and severity levels. Every event class must implement a unique code and a message() method.
Severity Mixins
Events inherit their log levels from specific mixins:
DebugLevel: Detailed information for troubleshooting.InfoLevel: General operational messages.WarnLevel: Indicators of potential issues or deprecations.ErrorLevel: Critical failures.
Sources: dbt-adapters/src/dbt/adapters/events/README.md:21-25, dbt-adapters/src/dbt/adapters/events/types.py:1-8
Key Event Categories
| Code Range | Category | Description |
|---|---|---|
| D001 - D999 | Deprecations | Warnings about features to be removed (e.g., D005 for function deprecation). |
| E001 - E004 | General Adapter | Generic debug, info, warning, and error events for adapters. |
| E005 - E012 | Connections | Events for acquiring, reusing, closing, or failing rollbacks on connections. |
| E013 - E031 | Database/Cache | Cache misses, listing relations, SQL query execution, and schema changes. |
| E034 - E044 | Lifecycle/Catalog | Adapter registration, plugin loading errors, and catalog generation status. |
Sources: dbt-adapters/src/dbt/adapters/events/types.py:18-250
Database Connection Events
The system extensively tracks the lifecycle of database connections. This includes tracking when a connection is pulled from a pool versus when a new one is opened.
The sequence diagram illustrates the event triggers during a standard database interaction cycle.
Sources: dbt-adapters/src/dbt/adapters/events/types.py:75-150, CLAUDE.md:Framework Core Classes
SQL Execution Tracking
SQL events capture the raw SQL content and the elapsed time for execution, which is critical for performance monitoring.
SQLQuery(E016): Captures theconn_nameandsqlstring.SQLQueryStatus(E017): Captures the resultingstatusandelapsedtime.
Sources: dbt-adapters/src/dbt/adapters/events/types.py:138-148, dbt-adapters/CHANGELOG.md:1.10.4
Cache and Schema Events
The events module provides visibility into dbt's internal relations cache and schema operations. These events are often "DynamicLevel" or "DebugLevel" due to their potential volume.
Cache Action Types (E022)
The CacheAction event tracks several internal states:
add_link: When one relation references another.add_relation: Adding a new relation to the cache.drop_relation: Removing a relation.rename_relation: Tracking identity changes for relations.uncached_relation: Warning when a referenced relation is missing from the cache.
Sources: dbt-adapters/src/dbt/adapters/events/types.py:173-205
Schema Lifecycle
Events like SchemaCreation (E020) and SchemaDrop (E021) log the specific relation involved in DDL operations.
Sources: dbt-adapters/src/dbt/adapters/events/types.py:161-171
Implementation Details
Creating a New Event
To add a new event, developers must define it in the central protos repository and then compile it into the Python types.py file.
Requirements:
- A unique alphanumeric code (e.g.,
I049). - A log level mixin.
- A
message()method returning a string.
Example Implementation:
class PartialParsingDeletedExposure(DebugLevel):
def code(self):
return "I049"
def message(self) -> str:
return f"Partial parsing: deleted exposure {self.unique_id}"
Sources: dbt-adapters/src/dbt/adapters/events/README.md:21-35, AGENTS.md:Changelog
Metadata Recording
For testing and replay purposes, the system can record operation details. Subclasses of BaseColumns can record adapter.get_columns_in_relation and other available functions to allow for execution replay without a live database.
Sources: dbt-adapters/CHANGELOG.md:1.17.3, AGENTS.md:External Catalog Integrations
Summary
Events & Logging in dbt-adapters provides a standardized, protobuf-backed mechanism for observing the internal state of database adapters. By categorizing events from connection management to cache manipulation, it enables developers to debug complex DDL operations and monitor performance through structured log data.