thirdeye-logging 0.1.0

Third Eye's Python logging SDK for enriched application logs with optional direct storage in your own database

Third Eye Python Logging SDK

Third Eye's Python logging SDK enriches standard Python logs with application and source context, with optional direct storage in your own database.

It supports familiar logging methods such as debug, info, warning, error, exception, and critical, while automatically capturing useful metadata including:

• Service, environment, and application version
• Git commit SHA
• Source file, function, and line number
• Trace, span, request, and user identifiers
• Message templates and custom attributes
• Optional stack information

When THIRDEYE_DATABASE_URL is configured, the SDK writes enriched logs directly to your database. Without it, logs only use Python's local logging module.

Installation

pip install thirdeye-logging

The distribution name is thirdeye-logging; the Python import remains thirdeye. The base installation supports local logging without installing database drivers.

Usage

Use Third Eye like Python's standard logging library:

import thirdeye

logger = thirdeye.getLogger(__name__)

logger.info(
    "Order %s processed",
    "ord_123",
    trace_id="trace_123",
    user_id="user_456",
)

trace_id, span_id, request_id, and user_id are not stored by the default database schema. Add their column names to THIRDEYE_DATABASE_COLUMNS when you want to persist them. Other custom attributes are only stored when attributes is selected.

Third Eye configures basic console logging at INFO when the application has not already configured Python logging. To use a custom format, configure logging before importing Third Eye; the existing configuration takes precedence:

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s %(message)s",
)

import thirdeye

If you configure logging after importing Third Eye, pass force=True to logging.basicConfig(...) so Python replaces the existing basic configuration.

Use thirdeye.set_log_level(...) to change the level for existing and future Third Eye loggers, for example thirdeye.set_log_level(thirdeye.LogLevel.DEBUG).

Loggers returned by getLogger send events through one shared uploader. Importing Third Eye does not connect to or modify the database. The uploader initializes the database and creates or updates the table when the first application log is sent.

Database setup

Third Eye supports PostgreSQL, MySQL, SQLite, and Microsoft SQL Server.

Install the extra for the database you use:

Database	Installation
PostgreSQL	pip install "thirdeye-logging[postgresql]"
MySQL	pip install "thirdeye-logging[mysql]"
SQLite	pip install "thirdeye-logging[sqlite]"
Microsoft SQL Server	pip install "thirdeye-logging[mssql]"

If the selected database dependency is missing, Third Eye logs a local warning and continues running without uploading that event.

Set the database URL before importing the library:

export THIRDEYE_DATABASE_URL="postgresql://user:password@localhost/database"

You may optionally configure the destination table and stored columns:

export THIRDEYE_DATABASE_TABLE="thirdeye_logs"
export THIRDEYE_DATABASE_COLUMNS="timestamp,level,message,service,environment,trace_id,user_id,attributes"

Table configuration

Third Eye creates the table on the first upload if it does not exist. The default table is thirdeye_logs, and its default columns are timestamp, level, service, and message. Identifiers and custom attributes supplied to a log event are only persisted when their columns are selected.

Set THIRDEYE_DATABASE_COLUMNS to a comma-separated list to select different columns. When the table already exists, Third Eye adds any selected columns that are missing. It does not change or remove existing columns. All selected columns are nullable.

Available columns:

Column	Description	Default
timestamp	UTC time when the log event was created.	✓
level	Log level such as INFO, WARNING, or ERROR.	✓
message	Formatted log message.	✓
args	JSON array of arguments passed to the message template.
template	Original unformatted message template.
service	Service name discovered from environment or project metadata.	✓
environment	Application environment such as production or staging.
version	Service or application version.
git_sha	Git commit SHA.
trace_id	Trace identifier supplied with the log event.
span_id	Span identifier supplied with the log event.
request_id	Request identifier supplied with the log event.
user_id	User identifier supplied with the log event.
file	Source file that emitted the log.
line	Source line number.
function	Function that emitted the log.
stack	Exception traceback or stack information requested with stack_info.
attributes	JSON object containing other keyword attributes.

Use JSON-capable columns for args and attributes when providing an existing table.

Privacy

Third Eye does not send logs or credentials to Third Eye Tech. Without THIRDEYE_DATABASE_URL, logs remain local. When a database URL is configured, the SDK writes directly to that database.

Log messages can contain sensitive information. Avoid logging credentials or personal data, use pseudonymous identifiers, and select optional metadata columns only when needed. Source paths, stack traces, request and user identifiers, message arguments, and custom attributes are not stored by default.