Metadata-Version: 2.4
Name: thirdeye-logging
Version: 0.1.0
Summary: Third Eye's Python logging SDK for enriched application logs with optional direct storage in your own database
Author-email: Third Eye Tech <help@3rdeye.com>
License: MIT License
        
        Copyright (c) 2026 Third Eye Tech
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/3rd-eye-tech/logging-python
Project-URL: Issues, https://github.com/3rd-eye-tech/logging-python/issues
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: sqlite
Requires-Dist: SQLAlchemy>=2.0; extra == "sqlite"
Provides-Extra: postgresql
Requires-Dist: SQLAlchemy>=2.0; extra == "postgresql"
Requires-Dist: psycopg[binary]>=3.2; extra == "postgresql"
Provides-Extra: mysql
Requires-Dist: SQLAlchemy>=2.0; extra == "mysql"
Requires-Dist: mysql-connector-python>=9.0; extra == "mysql"
Provides-Extra: mssql
Requires-Dist: SQLAlchemy>=2.0; extra == "mssql"
Requires-Dist: pyodbc>=5.0; extra == "mssql"
Dynamic: license-file

# 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

```bash
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:

```python
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:

```python
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:

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

You may optionally configure the destination table and stored columns:

```bash
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.
