Metadata-Version: 2.5
Name: monitaudit
Version: 1.3.1
Summary: A lightweight, low-overhead Python framework for real-time log monitoring and structured system auditing.
Project-URL: Homepage, https://github.com/informatie/monitaudit
Project-URL: Issues, https://github.com/informatie/monitaudit/issues
Author-email: Informatie <informatie@nednazit.nl>
License-Expression: MIT
License-File: LICENSE
Keywords: audit-trail,logging,monitoring,observability,telemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.12
Requires-Dist: delta-spark>=4.4.1
Requires-Dist: py4j>=0.10.9.9
Requires-Dist: pydantic>=2.0
Requires-Dist: pyspark[sql]>=4.2.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: structlog>=26.1.0
Requires-Dist: types-pyyaml>=6.0.12.20261030
Description-Content-Type: text/markdown

# monitaudit 🔍 🛡️

A lightweight Python observability and audit framework providing standardized tracing, correlation, safe structured events, and configurable sinks.

`monitaudit` provides a clear, developer-friendly API for structured logging, application tracing, runtime diagnostics, and audit events.

It is designed to keep observability concerns explicit and consistent without spreading logging and tracing logic throughout application code.

## Key Highlights

- **Structured Logging**  
  Capture consistent structured application events with contextual data that can be processed, queried, and analysed.

- **Function Tracing**  
  Trace function execution using start, end, and error events, including execution duration and optional parameter and return-value capture.

- **Correlation and Nested Tracing**  
  Correlate related operations using `call_id` and `parent_call_id` relationships across nested function calls.

- **Exception Diagnostics**  
  Capture structured exception information and tracebacks while preserving normal application exception behaviour.

- **Sensitive Data Protection**  
  Protect passwords, tokens, secrets, and other sensitive values when capturing function parameters and structured data.

- **Audit Tracking**  
  Record important application actions, events, and state changes for operational and audit purposes.

- **Configurable Sinks**  
  Route structured events to configurable output destinations.

- **Sink Failure Isolation**  
  Configure how sink failures are handled so observability failures do not unnecessarily disrupt application logic.

- **Modern Python**  
  Designed around type annotations, explicit APIs, structured models, and modern Python development practices.

## Installation

Install `monitaudit` from PyPI using `uv`:

```bash
uv add monitaudit
```

Or using `pip`:

```bash
pip install monitaudit
```

## Configuration

MonitAudit uses a `config/monitaudit` directory containing its default and runtime configuration:

```text
your-application/
├── config/
│   └── monitaudit/
│       ├── monitaudit.properties
│       └── monitaudit.runtime
└── main.py
```

The two configuration files have separate responsibilities:

- `monitaudit.properties` defines the standard MonitAudit defaults.
- `monitaudit.runtime` defines application-specific and environment-specific runtime configuration.

### `monitaudit.properties`

`monitaudit.properties` contains the default MonitAudit configuration.

These values define standard logging and tracing behaviour and normally remain the same across runtime environments.

Example:

```properties
# config/monitaudit/monitaudit.properties

logging.level=INFO
logging.timer=true
logging.show_parameters=true
logging.max_parameter_length=1000
logging.sink_failure_mode=continue
logging.file_cycle=10
```

These settings control behaviour such as:

- logging level
- execution timing
- function parameter capture
- maximum captured parameter length
- sink failure handling
- file lifecycle behaviour

For example:

```properties
logging.show_parameters=true
```

controls whether function parameters may be included in trace events.

The maximum captured parameter length can be limited using:

```properties
logging.max_parameter_length=1000
```

### `monitaudit.runtime`

`monitaudit.runtime` contains application-specific and environment-specific runtime configuration.

Although the runtime file does not use a `.yaml` extension, its contents use YAML syntax.

Example:

```yaml
# config/monitaudit/monitaudit.runtime

monitaudit:
  application: my-application

  environments:
    dev:
      logging:
        level: DEBUG

    test:
      logging:
        level: INFO

    prod:
      logging:
        level: INFO
```

This allows the same application to use different MonitAudit settings without changing application code.

### Selecting an Environment

The runtime environment can be selected using one of the supported environment variables.

Using `MONITAUDIT_ENVIRONMENT`:

```bash
export MONITAUDIT_ENVIRONMENT=dev
```

Alternatively:

```bash
export MONITAUDIT_ENV=dev
```

or:

```bash
export ENV=dev
```

For example:

```bash
MONITAUDIT_ENV=dev uv run python main.py
```

The selected environment determines which environment-specific runtime configuration is applied.

## Basic Usage

A minimal MonitAudit application requires only initialization and a log event:

```python
import monitaudit


mta = monitaudit.monitaudit_init()

mta.info("Hello from MonitAudit")
```

The resulting MonitAudit instance can be shared by the application for structured logging and tracing.

## Structured Logging

MonitAudit provides standard logging levels through a consistent interface:

```python
import monitaudit


mta = monitaudit.monitaudit_init()

mta.debug("Processing data")
mta.info("Application started")
mta.warning("Example warning")
mta.error("Example error")
```

Structured application data can be attached to events:

```python
mta.info(
    "Order processed",
    order_id="ORD-1001",
    customer_id="CUST-42",
    status="completed",
)
```

Keeping operational data structured makes events easier to process, filter, query, and analyse than embedding all information into formatted message strings.

## Function Tracing

Use `@mta.trace` to instrument application functions:

```python
import monitaudit


mta = monitaudit.monitaudit_init()


@mta.trace
def calculate_total(price: float, quantity: int) -> float:
    return price * quantity


def main() -> None:
    mta.info("Application started")

    total = calculate_total(12.50, 4)

    mta.info(
        "Calculation completed",
        total=total,
    )

    mta.info("Application completed")


if __name__ == "__main__":
    main()
```

Tracing allows application execution to be recorded consistently without manually implementing start, end, duration, and error logging inside every function.

Depending on configuration, trace events can include information such as:

- function start
- function end
- function error
- execution duration
- function parameters
- return values
- exception details
- tracebacks
- `call_id`
- `parent_call_id`

## Nested Tracing

Traced functions can call other traced functions.

MonitAudit can correlate these operations through `call_id` and `parent_call_id` relationships.

For example:

```python
import monitaudit


mta = monitaudit.monitaudit_init()


@mta.trace
def calculate_tax(amount: float) -> float:
    return amount * 0.21


@mta.trace
def calculate_total(amount: float) -> float:
    tax = calculate_tax(amount)
    return amount + tax


def main() -> None:
    total = calculate_total(100.0)

    mta.info(
        "Calculation completed",
        total=total,
    )


if __name__ == "__main__":
    main()
```

This creates a relationship between the parent `calculate_total()` call and the nested `calculate_tax()` call.

## Error Handling

Application exceptions can be logged explicitly through `mta.error()` while preserving the application's normal exception behaviour.

```python
import monitaudit


mta = monitaudit.monitaudit_init()


def process_data() -> None:
    raise RuntimeError("Processing failed")


def main() -> None:
    mta.info("Application started")

    try:
        process_data()
    except Exception as exc:
        mta.error(
            "Application failed",
            error_type=type(exc).__name__,
            error_message=str(exc),
        )
        raise


if __name__ == "__main__":
    main()
```

For traced functions, MonitAudit can capture structured error and traceback information as part of the trace lifecycle.

For example:

```python
import monitaudit


mta = monitaudit.monitaudit_init()


@mta.trace
def process_data() -> None:
    raise RuntimeError("Processing failed")


def main() -> None:
    process_data()


if __name__ == "__main__":
    main()
```

The tracing layer can record the failed function call while allowing the original exception to propagate normally.

## Parameter Capture

Function parameter capture can be enabled through:

```properties
logging.show_parameters=true
```

For example:

```python
@mta.trace
def calculate_total(price: float, quantity: int) -> float:
    return price * quantity
```

When parameter capture is enabled, the trace can include contextual information about the function invocation.

Parameter values can be bounded using:

```properties
logging.max_parameter_length=1000
```

This prevents unexpectedly large parameter representations from producing excessively large observability events.

## Sensitive Data

Observability data should never expose credentials or other sensitive information.

Parameters such as:

```text
password
token
secret
```

should be protected when trace parameters or structured application data are captured.

Avoid explicitly logging secrets:

```python
# Avoid
mta.info(
    "Login attempt",
    password=password,
    token=token,
)
```

Prefer non-sensitive identifiers and operational context:

```python
mta.info(
    "Login completed",
    user_id=user_id,
    status="success",
)
```

This provides useful observability information without intentionally placing credentials in structured events.

## Configurable Sinks

MonitAudit can route events to configured sinks.

This separates event creation from event delivery:

```text
Application
    │
    ▼
 MonitAudit
    │
    ├── Console
    ├── File
    ├── JSON
    ├── Delta
    └── Memory
```

Application code can therefore use the same logging and tracing interface regardless of the configured output destination.

Sink configuration belongs in the MonitAudit configuration rather than being spread throughout application code.

## Sink Failure Handling

Sink failure behaviour can be controlled through:

```properties
logging.sink_failure_mode=continue
```

Using `continue` allows application execution to continue when an observability sink fails.

This helps maintain an important separation:

> Failure of the observability layer should not unnecessarily become failure of the observed application.

The appropriate failure policy should still be selected based on the application's operational and audit requirements.

## Local Development

When developing MonitAudit and a consuming application on the same machine, install the local project as an editable dependency:

```bash
uv add --editable /home/zadmin/projects/monitaudit
```

The consuming application then uses the local MonitAudit source directly.

This allows library changes to be tested immediately without publishing a new package release to PyPI.

## Examples

Complete examples, configuration files, sink demonstrations, tracing scenarios, and integration patterns are maintained in the dedicated examples repository:

👉 **[monitaudit-examples](https://github.com/informatie/monitaudit-examples)**

The examples repository provides practical demonstrations of:

- MonitAudit configuration
- structured logging
- function tracing
- parameter capture
- sensitive-value redaction
- nested tracing
- `call_id` and `parent_call_id`
- execution duration
- return values
- exception handling
- traceback capture
- handled child failures
- parent trace continuation
- configurable sinks

The examples repository is the recommended starting point for learning how to configure and integrate MonitAudit into an application.

## Project Philosophy

MonitAudit is not intended to replace application logic or become a general-purpose application framework.

Its responsibility is deliberately focused:

> Provide applications with a lightweight, consistent observability and audit layer for structured events, tracing, correlation, diagnostics, and configurable event delivery.

Application code should focus on business behaviour.

MonitAudit should provide the surrounding observability needed to understand that behaviour.

## License

See the `LICENSE` file for the project's licensing terms.

---

## Configuration

MonitAudit uses a `config/monitaudit` directory containing two configuration files:

```text
your-application/
├── config/
│   └── monitaudit/
│       ├── monitaudit.properties
│       └── monitaudit.runtime
└── main.py
```

The two configuration files have separate responsibilities:

- `monitaudit.properties` defines the standard MonitAudit defaults.
- `monitaudit.runtime` defines application-specific and environment-specific runtime configuration.

### `monitaudit.properties`

`monitaudit.properties` contains the default MonitAudit configuration.

These values define the standard logging and tracing behaviour and normally remain the same across runtime environments.

Example:

```properties
# config/monitaudit/monitaudit.properties

logging.level=INFO
logging.timer=true
logging.show_parameters=true
logging.max_parameter_length=1000
logging.sink_failure_mode=continue
logging.file_cycle=10
```

These settings control behaviour such as:

- logging level
- execution timing
- function parameter capture
- maximum captured parameter length
- sink failure handling
- file lifecycle behaviour

### `monitaudit.runtime`

`monitaudit.runtime` contains application-specific and environment-specific runtime configuration.

Although the file does not use a `.yaml` extension, its contents use YAML syntax.

Example:

```yaml
# config/monitaudit/monitaudit.runtime

monitaudit:
  application: my-application

  environments:
    dev:
      logging:
        level: DEBUG

    test:
      logging:
        level: INFO

    prod:
      logging:
        level: INFO
```

### Selecting an Environment

The runtime environment can be selected using one of the supported environment variables:

```bash
export MONITAUDIT_ENVIRONMENT=dev
```

Alternatively:

```bash
export MONITAUDIT_ENV=dev
```

or:

```bash
export ENV=dev
```

For example:

```bash
MONITAUDIT_ENV=dev uv run python main.py
```

The selected environment determines which environment-specific runtime configuration is applied.

## Example 1: Minimal Usage

```python
import monitaudit


mta = monitaudit.monitaudit_init()

mta.info("Hello from MonitAudit")
```

## Example 2: Structured Logging

MonitAudit provides standard logging levels through a consistent interface:

```python
import monitaudit


mta = monitaudit.monitaudit_init()

mta.info("Application started")
mta.debug("Processing data")
mta.warning("Example warning")
mta.error("Example error")
```

Structured application data can be attached to events:

```python
mta.info(
    "Order processed",
    order_id="ORD-1001",
    customer_id="CUST-42",
    status="completed",
)
```

This keeps operational data structured instead of embedding all contextual information into formatted log messages.

## Example 3: Function Tracing

Use `@mta.trace` to instrument application functions:

```python
import monitaudit


mta = monitaudit.monitaudit_init()


@mta.trace
def calculate_total(price: float, quantity: int) -> float:
    return price * quantity


def main() -> None:
    mta.info("Application started")

    total = calculate_total(12.50, 4)

    mta.info(
        "Calculation completed",
        total=total,
    )

    mta.info("Application completed")


if __name__ == "__main__":
    main()
```

Depending on configuration, tracing can capture information such as:

- function start and end events
- execution duration
- function parameters
- return values
- errors and exception details
- tracebacks
- `call_id`
- `parent_call_id`

## Example 4: Error Handling

Application exceptions can be logged explicitly using `mta.error()` while preserving normal exception behaviour:

```python
import monitaudit


mta = monitaudit.monitaudit_init()


def process_data() -> None:
    raise RuntimeError("Processing failed")


def main() -> None:
    mta.info("Application started")

    try:
        process_data()
    except Exception as exc:
        mta.error(
            "Application failed",
            error_type=type(exc).__name__,
            error_message=str(exc),
        )
        raise


if __name__ == "__main__":
    main()
```

For traced functions, MonitAudit can capture structured error and traceback information as part of the trace lifecycle.

## More Examples

Complete examples, configuration files, sink demonstrations, tracing scenarios, and more advanced usage patterns are available in the dedicated examples repository:

👉 **[monitaudit-examples](https://github.com/informatie/monitaudit-examples)**

The examples repository covers practical scenarios including:

- configuration
- structured logging
- function tracing
- parameter capture
- sensitive-value redaction
- nested tracing
- `call_id` and `parent_call_id`
- execution duration
- return values
- exception handling
- traceback capture
- handled child failures
- parent trace continuation
- configurable sinks

The examples repository is the recommended starting point for more advanced MonitAudit configuration, tracing, sinks, and application integration.

---

# Complete Configuration Examples

The following examples show the complete Monitaudit configuration files.

## `config/monitaudit.properties`

````properties
# config/monitaudit.properties
#
# ==============================================================================
# MonitAudit - Default Library Configuration
# ==============================================================================
#
# This file contains the default configuration used by MonitAudit.
#
# Application-specific and environment-specific settings should normally be
# placed in:
#
#     config/monitaudit.runtime
#
# The runtime configuration can override defaults defined here.
#
# Recommended project structure:
#
#     your-application/
#     |
#     +-- config/
#     |   +-- monitaudit.properties
#     |   +-- monitaudit.runtime
#     |
#     +-- main.py
#
# Typical application initialisation:
#
#     import monitaudit
#
#     mta = monitaudit.monitaudit_init()
#
#     mta.info("Application started")
#
# ==============================================================================
# LOGGING
# ==============================================================================
#
# Default logging configuration.
#
# level
# -----
# Minimum logging level.
#
# Typical values:
#
#     DEBUG
#     INFO
#     WARNING
#     ERROR
#     CRITICAL
#
# Example:
#
#     logging.level=DEBUG
#
# For normal operation INFO is generally a suitable default.
#
# ------------------------------------------------------------------------------
#
# timer
# -----
# Controls timing information produced by MonitAudit tracing/instrumentation.
#
# Example:
#
#     logging.timer=true
#
# ------------------------------------------------------------------------------
#
# parameters
# ----------
# Controls whether parameters may be included in structured logging/tracing
# information.
#
# Example:
#
#     logging.parameters=true
#
# Do not assume that enabling this option makes arbitrary application data safe
# to log. Applications should still avoid passing secrets, credentials, tokens,
# passwords, or other sensitive information to logging calls.
#
# ------------------------------------------------------------------------------
#
# max_parameter_length
# --------------------
# Maximum length used when recording parameter values.
#
# Long values may be truncated according to MonitAudit's parameter handling.
#
# Example:
#
#     logging.max_parameter_length=1000
#
# ------------------------------------------------------------------------------
#
# sink_failure_mode
# -----------------
# Determines the configured policy for sink failures.
#
# Example:
#
#     logging.sink_failure_mode=continue
#
# The exact values accepted by the installed MonitAudit version should match the
# configuration model used by that release.
#
# ------------------------------------------------------------------------------
#
# file_cycle
# -----------------
# How long
#
# Example:
#
#     logging.sink_failure_mode=continue
#
# The exact values accepted by the installed MonitAudit version should match the
# configuration model used by that release.
#
# ==============================================================================

logging.level=INFO
logging.timer=true
logging.parameters=true
logging.max_parameter_length=1000
logging.sink_failure_mode=continue
logging.file_cycle=10


# ==============================================================================
# SINK CONFIGURATION
# ==============================================================================
#
# A sink determines where MonitAudit events are written.
#
# MonitAudit applications can configure output destinations such as:
#
#     Console
#     File
#     JSON
#     Delta
#
# Sink-specific runtime paths, table names, and environment-dependent settings
# are better placed in monitaudit.runtime when they differ between
# applications or environments.
#
# The examples below illustrate the intended configuration categories.
# Keep the actual property names aligned with the configuration models of the
# MonitAudit release being used.
# ==============================================================================


# ==============================================================================
# CONSOLE SINK
# ==============================================================================
#
# The console sink writes logging output to the application's console.
#
# Typical use:
#
#     Local development
#     Interactive execution
#     Containers
#     CI/CD diagnostics
#
# Example:
#
#     console_sink.enabled=true
#
# ==============================================================================

console_sink.enabled=false


# ==============================================================================
# FILE SINK
# ==============================================================================
#
# The file sink writes MonitAudit events to a text-based log file.
#
# Example runtime configuration:
#
#     file_sink:
#       enabled: true
#       path: output/file_sink/application.log
#
# Paths are application-specific, so the actual output path should preferably
# be configured in monitaudit.runtime rather than hard-coded into the
# library defaults.
#
# ==============================================================================

file_sink.enabled=false


# ==============================================================================
# JSON SINK
# ==============================================================================
#
# The JSON sink writes structured events in JSON format.
#
# This is useful when log output will subsequently be ingested or processed by
# another system.
#
# Example runtime configuration:
#
#     json_sink:
#       enabled: true
#       path: output/json_sink/application.jsonl
#
# Keep application-specific paths in monitaudit.runtime.
#
# ==============================================================================

json_sink.enabled=false


# ==============================================================================
# DELTA SINK
# ==============================================================================
#
# The Delta sink stores structured MonitAudit events in a Delta destination.
#
# From the MonitAudit configuration design, both the logical table and physical
# path belong in configuration rather than being hard-coded in Python.
#
# Example runtime configuration:
#
#     delta_sink:
#       enabled: true
#       table: main.logging.application
#       path: output/delta_sink/application
#
# Table and path values are application/environment-specific and should
# therefore normally be defined in monitaudit.runtime.
#
# ==============================================================================

delta_sink.enabled=false


# ==============================================================================
# EXAMPLE: DEVELOPMENT CONFIGURATION
# ==============================================================================
#
# The properties in this file establish defaults.
#
# A development application could override them from
# monitaudit.runtime, for example:
#
#     monitaudit:
#       application: example-application
#
#       logging:
#         level: INFO
#         timer: true
#         parameters: true
#         max_parameter_length: 1000
#         sink_failure_mode: continue
#
#       sinks:
#         console_sink:
#           enabled: false
#
#         json_sink:
#           enabled: false
#
#         file_sink:
#           enabled: false
#
#         delta_sink:
#           enabled: false
#
# ==============================================================================
# ENVIRONMENT SELECTION
# ==============================================================================
#
# Runtime environment selection is handled outside this properties file.
#
# MonitAudit applications may select their runtime environment using:
#
#     MONITAUDIT_ENVIRONMENT
#     MONITAUDIT_ENV
#     ENV
#
# Example:
#
#     MONITAUDIT_ENV=dev uv run python main.py
#
# Environment-specific configuration belongs in monitaudit.runtime.
#
# ==============================================================================
# RECOMMENDED RESPONSIBILITY SPLIT
# ==============================================================================
#
# monitaudit.properties
# ---------------------
#
#     MonitAudit defaults
#     Logging defaults
#     Default feature behaviour
#     Default sink enablement
#
#
# monitaudit.runtime
# -----------------------
#
#     Application name
#     Environment-specific overrides
#     Output paths
#     Delta table names
#     Application sink configuration
#     Deployment-specific configuration
#
#
# Python application
# ------------------
#
#     import monitaudit
#
#     mta = monitaudit.monitaudit_init()
#
#     mta.info("Application started")
#
# Keeping these responsibilities separate prevents application-specific
# configuration from becoming part of the MonitAudit library defaults.
# ==============================================================================
````

## `config/monitaudit.runtime`

````yaml
# config/monitaudit.yaml
#
# ==============================================================================
# MonitAudit - Runtime Configuration
# ==============================================================================
#
# This file contains application-specific MonitAudit configuration.
#
# MonitAudit configuration is split into:
#
#   monitaudit.properties
#       Library defaults.
#
#   monitaudit.yaml
#       Application/runtime configuration and overrides.
#
# Recommended project structure:
#
#   your-application/
#   |
#   +-- config/
#   |   +-- monitaudit.properties
#   |   +-- monitaudit.yaml
#   |
#   +-- main.py
#
# Typical application initialisation:
#
#   import monitaudit
#
#   mta = monitaudit.monitaudit_init()
#
#   mta.info("Application started")
#
# ==============================================================================

monitaudit:

  # ============================================================================
  # APPLICATION
  # ============================================================================
  #
  # Logical name of the application producing MonitAudit events.
  #
  # Choose a stable name that identifies the application rather than the
  # individual server or process running it.
  #
  # Examples:
  #
  #   customer-api
  #   data-ingestion
  #   billing-service
  #   monitaudit-example
  #
  # ============================================================================

  application: my-application


  # ============================================================================
  # LOGGING
  # ============================================================================
  #
  # Application logging and tracing behaviour.
  #
  # Values specified here override the corresponding MonitAudit defaults.
  #
  # ============================================================================

  logging:

    # --------------------------------------------------------------------------
    # level
    # --------------------------------------------------------------------------
    #
    # Minimum logging level.
    #
    # Common values:
    #
    #   DEBUG
    #   INFO
    #   WARNING
    #   ERROR
    #   CRITICAL
    #
    # DEBUG is useful during development.
    # INFO is recommended as a normal application starting point.
    #
    # --------------------------------------------------------------------------

    level: INFO


    # --------------------------------------------------------------------------
    # timer
    # --------------------------------------------------------------------------
    #
    # Enables timing information for supported tracing/instrumentation.
    #
    # Example:
    #
    #   timer: true
    #
    # --------------------------------------------------------------------------

    timer: true


    # --------------------------------------------------------------------------
    # parameters
    # --------------------------------------------------------------------------
    #
    # Controls whether supported tracing/logging operations can include
    # parameter information.
    #
    # Applications should still avoid logging passwords, authentication
    # credentials, tokens, secrets, or other sensitive information.
    #
    # --------------------------------------------------------------------------

    parameters: true


    # --------------------------------------------------------------------------
    # max_parameter_length
    # --------------------------------------------------------------------------
    #
    # Maximum configured length for logged parameter values.
    #
    # Example:
    #
    #   max_parameter_length: 1000
    #
    # --------------------------------------------------------------------------

    max_parameter_length: 1000


    # --------------------------------------------------------------------------
    # sink_failure_mode
    # --------------------------------------------------------------------------
    #
    # Defines the configured behaviour when an output sink fails.
    #
    # The "continue" mode allows the application to continue processing when
    # supported by the installed MonitAudit version.
    #
    # --------------------------------------------------------------------------

    sink_failure_mode: continue


  # ============================================================================
  # SINKS
  # ============================================================================
  #
  # Sinks determine where MonitAudit events are written.
  #
  # Individual sinks can be enabled or disabled independently.
  #
  # This complete example contains:
  #
  #   console_sink
  #   file_sink
  #   json_sink
  #   delta_sink
  #
  # ============================================================================

  sinks:

    # ==========================================================================
    # CONSOLE SINK
    # ==========================================================================
    #
    # Writes MonitAudit output to the console.
    #
    # Useful for:
    #
    #   - local development
    #   - interactive execution
    #   - containers
    #   - CI/CD diagnostics
    #
    # ==========================================================================

    console_sink:
      enabled: true


    # ==========================================================================
    # FILE SINK
    # ==========================================================================
    #
    # Writes MonitAudit events to a text log file.
    #
    # Relative paths should be interpreted consistently by the application and
    # MonitAudit configuration loader.
    #
    # Example destination:
    #
    #   output/file_sink/application.log
    #
    # Set enabled to false when the file sink is not required.
    #
    # ==========================================================================

    file_sink:
      enabled: false
      path: output/file_sink/application.log


    # ==========================================================================
    # JSON SINK
    # ==========================================================================
    #
    # Writes structured MonitAudit events to JSON output.
    #
    # A .jsonl extension can be used when each log event is stored as an
    # individual JSON record on a separate line.
    #
    # Example destination:
    #
    #   output/json_sink/application.jsonl
    #
    # ==========================================================================

    json_sink:
      enabled: false
      path: output/json_sink/application.jsonl


    # ==========================================================================
    # DELTA SINK
    # ==========================================================================
    #
    # Writes structured events to the configured Delta destination.
    #
    # Both the logical table name and physical path are configuration values.
    # They should not need to be hard-coded in the application.
    #
    # Local example:
    #
    #   table: main.logging.application
    #   path: output/delta_sink/application
    #
    # Set enabled to false when Delta output is not required.
    #
    # ==========================================================================

    delta_sink:
      enabled: false
      table: main.logging.application
      path: output/delta_sink/application


# ==============================================================================
# EXAMPLE CONFIGURATIONS
# ==============================================================================
#
# The examples below are documentation only.
#
# Do not uncomment all examples at the same time if they duplicate the active
# configuration above.
#
#
# ------------------------------------------------------------------------------
# CONSOLE-ONLY APPLICATION
# ------------------------------------------------------------------------------
#
# monitaudit:
#   application: my-console-application
#
#   logging:
#     level: DEBUG
#     timer: true
#     parameters: true
#     max_parameter_length: 1000
#     sink_failure_mode: continue
#
#   sinks:
#     console_sink:
#       enabled: true
#
#
# ------------------------------------------------------------------------------
# FILE LOGGING APPLICATION
# ------------------------------------------------------------------------------
#
# monitaudit:
#   application: my-file-application
#
#   logging:
#     level: INFO
#     timer: true
#     parameters: true
#     max_parameter_length: 1000
#     sink_failure_mode: continue
#
#   sinks:
#     console_sink:
#       enabled: true
#
#     file_sink:
#       enabled: true
#       path: output/file_sink/application.log
#
#
# ------------------------------------------------------------------------------
# JSON LOGGING APPLICATION
# ------------------------------------------------------------------------------
#
# monitaudit:
#   application: my-json-application
#
#   logging:
#     level: INFO
#     timer: true
#     parameters: true
#     max_parameter_length: 1000
#     sink_failure_mode: continue
#
#   sinks:
#     console_sink:
#       enabled: true
#
#     json_sink:
#       enabled: true
#       path: output/json_sink/application.jsonl
#
#
# ------------------------------------------------------------------------------
# ALL SINKS
# ------------------------------------------------------------------------------
#
# monitaudit:
#   application: my-application
#
#   logging:
#     level: DEBUG
#     timer: true
#     parameters: true
#     max_parameter_length: 1000
#     sink_failure_mode: continue
#
#   sinks:
#     console_sink:
#       enabled: true
#
#     file_sink:
#       enabled: true
#       path: output/file_sink/application.log
#
#     json_sink:
#       enabled: true
#       path: output/json_sink/application.jsonl
#
#     delta_sink:
#       enabled: true
#       table: main.logging.application
#       path: output/delta_sink/application
#
#
# ==============================================================================
# ENVIRONMENT SELECTION
# ==============================================================================
#
# When the MonitAudit configuration loader supports environment selection,
# the application environment can be selected externally.
#
# Supported environment-variable names in the current MonitAudit design:
#
#   MONITAUDIT_ENVIRONMENT
#   MONITAUDIT_ENV
#   ENV
#
# Example:
#
#   MONITAUDIT_ENV=dev uv run python main.py
#
# Do not store secrets, passwords, PyPI tokens, access tokens, connection
# credentials, or other sensitive values directly in this file.
#
# ==============================================================================
# BASIC PYTHON USAGE
# ==============================================================================
#
#   import monitaudit
#
#
#   mta = monitaudit.monitaudit_init()
#
#   mta.info("Application started")
#   mta.debug("Processing data")
#   mta.warning("Example warning")
#
#
# ==============================================================================
````
