vedatrace 0.1.0

Production-grade logging SDK for VedaTrace

VedaTrace Python SDK

Production-grade logging SDK for VedaTrace (Python 3.10+).

Table of Contents

• Features
• Stability
• Installation
• Quickstart
• Configuration
• Transports
• Batching (Opt-in)
• Retry (HTTP only)
• Child Loggers
• Error Handling & Safety
• Resource Management (flush/close)
• API Reference
• Release Process (Maintainers)
• License

Features

• Log levels aligned to parity: debug, info, warning, error, fatal
• Structured log records with UTC ISO-8601 timestamps
• Default transports: Console (optional) + HTTP ingest
• Custom transport support via config.transports
• Opt-in batching with threshold + interval flush
• HTTP-only fixed-delay retries
• Child loggers with metadata precedence support
• Safe public API: logger methods do not raise user-facing exceptions

Stability

Version 0.1.0 introduces a stable public API for:

• Logger
• Config
• Transports
• Batching
• Retry
• Child loggers

Breaking changes may still occur before 1.0.

Installation

python -m pip install vedatrace

For local development:

python -m pip install -e .

Quickstart

from vedatrace import VedaTrace

logger = VedaTrace(api_key="YOUR_API_KEY", service="my-service")
logger.info("hello from vedatrace")

Configuration

from vedatrace import BatchingConfig, RetryConfig, VedaTrace, VedaTraceConfig

config = VedaTraceConfig(
    api_key="YOUR_API_KEY",
    service="my-service",
    console_enabled=True,
    batching=BatchingConfig(enabled=False, batch_size=10, flush_interval_seconds=5.0),
    retry=RetryConfig(max_retries=0, retry_delay_seconds=0.0),
)

logger = VedaTrace(api_key="YOUR_API_KEY", service="my-service", config=config)

Transports

Default behavior:

• Console transport is enabled when config.console_enabled is True
• HTTP transport is enabled by default

Custom transports:

• Provide config.transports to fully override default transport creation

Batching (Opt-in)

Batching is disabled by default and must be enabled in BatchingConfig.

from vedatrace import BatchingConfig, VedaTrace, VedaTraceConfig

config = VedaTraceConfig(
    api_key="YOUR_API_KEY",
    service="my-service",
    batching=BatchingConfig(enabled=True, batch_size=10, flush_interval_seconds=5.0),
)

logger = VedaTrace(api_key="YOUR_API_KEY", service="my-service", config=config)
logger.info("batched log")
logger.flush()

Retry (HTTP only)

Retries are fixed-delay and apply only to the default HTTP transport.

from vedatrace import RetryConfig, VedaTrace, VedaTraceConfig

config = VedaTraceConfig(
    api_key="YOUR_API_KEY",
    service="my-service",
    retry=RetryConfig(max_retries=3, retry_delay_seconds=1.0),
    console_enabled=False,
)

logger = VedaTrace(api_key="YOUR_API_KEY", service="my-service", config=config)

If retries are exhausted, on_error receives the final failure.

Child Loggers

from vedatrace import VedaTrace

parent = VedaTrace(api_key="YOUR_API_KEY", service="my-service")
api_logger = parent.child({"module": "api"})
api_logger.info("request handled", {"request_id": "123"})

Metadata precedence:

• parent defaults < child defaults < per-call metadata

child.close() does not tear down shared engine resources.

Error Handling & Safety

• Public logger methods are non-throwing (debug/info/warning/error/fatal/flush/close)
• Internal failures are routed to on_error(Exception) when configured
• SDK avoids exposing API keys in logs/errors

Resource Management (flush/close)

• flush() forces pending batches to be sent
• close() flushes and then closes owned resources
• Child loggers share engine resources; parent logger owns teardown

API Reference

Factory:

• VedaTrace(api_key: str, service: str, *, config: VedaTraceConfig | None = None) -> Logger

Logger:

• debug(message: str, metadata: Metadata | None = None) -> None
• info(message: str, metadata: Metadata | None = None) -> None
• warning(message: str, metadata: Metadata | None = None) -> None
• error(message: str, metadata: Metadata | None = None) -> None
• fatal(message: str, metadata: Metadata | None = None) -> None
• child(default_metadata: Metadata | None = None, *, service: str | None = None) -> Logger
• flush() -> None
• close() -> None

Config classes:

• VedaTraceConfig(api_key, service, console_enabled=True, batching=BatchingConfig(...), retry=RetryConfig(...), transports=None, on_error=None)
• BatchingConfig(enabled=False, batch_size=10, flush_interval_seconds=5.0)
• RetryConfig(max_retries=0, retry_delay_seconds=0.0)

Transport types:

• Transport protocol:
  • emit(records: list[LogRecord]) -> None
  • close() -> None
• Included transports:
  • ConsoleTransport
  • HttpTransport

Behavior notes:

• Public log methods never raise.
• Internal failures route to on_error(Exception) when configured.
• Batching is opt-in.
• Retry applies to HTTP transport only.
• child.close() does not tear down the shared engine.

Release Process (Maintainers)

1. Bump version in:

• src/vedatrace/__init__.py
• pyproject.toml
• CHANGELOG.md

2. Run:

• python -m unittest -v
• python -m compileall src

3. Build:

• python -m build

4. Validate:

• twine check dist/*

5. Publish (when ready):

• python -m pip install twine
• twine upload dist/*

Notes:

• Never force push release commits.
• Tag releases using:
• git tag v0.1.0
• git push origin v0.1.0

License

MIT