tgedr-observability 0.0.1__tar.gz

tgedr_observability-0.0.1/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.3
+Name: tgedr-observability
+Version: 0.0.1
+Summary: simple observability solution
+Author: developer
+Author-email: developer <developer@email.com>
+Requires-Dist: opentelemetry-api>=1.44.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.44.0
+Requires-Dist: opentelemetry-sdk>=1.44.0
+Requires-Dist: pandas>=2.3.0,<3.0.0
+Requires-Dist: tgedr-pycommons>=1.2.1
+Requires-Python: >=3.12, <3.13
+Description-Content-Type: text/markdown
+
+# tgedr-observability
+
+![Coverage](./coverage.svg)
+[![PyPI](https://img.shields.io/pypi/v/tgedr-observability)](https://pypi.org/project/tgedr-observability/)
+
+## overview
+
+This repository is an early-stage observability toolkit built around a small Python package and a companion local monitoring stack. The Docker side is the main operational surface: an OpenTelemetry collector receives telemetry and routes metrics, logs, and traces into dedicated backends for storage and analysis. In practice, the project acts as a foundation for collecting, storing, and exploring observability data rather than as a finished application.
+
+## development
+- main requirements:
+  - _uv_  
+  - _bash_
+- Clone the repository like this:
+
+  ``` bash
+  git clone git@github.com:jtviegas/observability
+  ```
+- cd into the folder: `cd observability`
+- install requirements: `./helper.sh reqs`
+
+## source code guide
+
+The Python package lives under `src/tgedr_observability` and currently exposes three modules:
+
+- `commons.py`: shared constants and common types.
+- `metrics.py`: singleton wrapper for OpenTelemetry metrics setup and recording.
+- `logs.py`: singleton wrapper for OpenTelemetry logs setup and recording.
+
+### commons.py
+
+`commons.py` contains:
+
+- `LOCAL_METRICS_URL`: default local OTLP HTTP endpoint for metrics (`http://localhost:4318/v1/metrics`).
+- `OtlpConfig`: dataclass with exporter endpoint and optional headers.
+- `ObservabilityError`: package-specific exception used for observability validation errors.
+
+### metrics.py
+
+`Metrics` is a singleton manager that lazily initializes a global OpenTelemetry `MeterProvider`.
+
+Initialization behavior:
+
+1. `Metrics.instance()` returns the singleton object.
+2. `init(service, otlp_config=None)` configures:
+   - `Resource` with `service.name`.
+   - `ConsoleMetricExporter` (always enabled).
+   - Optional `OTLPMetricExporter` over HTTP when `otlp_config` is passed.
+3. The configured provider is set globally with `metrics.set_meter_provider(provider)`.
+
+Metric naming convention:
+
+- Metric names must have at least two dot-separated parts, for example `orders.api.requests`.
+- Everything before the last segment is used as meter scope name.
+- Last segment is used as instrument name.
+- Invalid names raise `ObservabilityError`.
+
+Instruments managed by the class:
+
+- Counter path: internally uses `create_up_down_counter`.
+- Gauge path: uses `create_gauge` with unit inferred from suffix (`_s` -> `s`, otherwise `1`).
+- Histogram path: uses `create_histogram` with the same unit inference.
+
+Public methods:
+
+- `add_to_counter(name, value, attributes=None)`
+- `add_to_gauge(name, value, attributes=None)`
+- `add_to_histogram(name, value, attributes=None)`
+- `force_flush(timeout_millis=10000)`
+- `shutdown()`
+- `app_shutdown()` (flush + shutdown convenience hook)
+
+### logs.py
+
+`Logs` is a singleton manager that lazily initializes a global OpenTelemetry `LoggerProvider`.
+
+Initialization behavior:
+
+1. `Logs.instance()` returns the singleton object.
+2. `init(service, otlp_config=None)` configures:
+   - `Resource` with `service.name`.
+   - `BatchLogRecordProcessor(ConsoleLogRecordExporter())` (always enabled).
+   - Optional `BatchLogRecordProcessor(OTLPLogExporter(...))` when `otlp_config` is passed.
+3. The provider is set globally with `set_logger_provider(provider)`.
+4. A `LoggingHandler` is attached through `logging.basicConfig(..., force=True)`.
+
+Public methods:
+
+- `force_flush(timeout_millis=10000)`
+- `shutdown()` (also detaches and closes the installed handler)
+- `app_shutdown()` (flush + shutdown convenience hook)
+
+## usage examples
+
+### metrics
+
+```python
+from tgedr_observability.commons import LOCAL_METRICS_URL, OtlpConfig
+from tgedr_observability.metrics import Metrics
+
+metrics_manager = Metrics.instance()
+metrics_manager.init(
+  service="orders-service",
+  otlp_config=OtlpConfig(endpoint=LOCAL_METRICS_URL),
+)
+
+metrics_manager.add_to_counter("orders.api.requests", 1, {"route": "/orders"})
+metrics_manager.add_to_histogram("orders.api.latency_s", 0.123, {"route": "/orders"})
+metrics_manager.force_flush()
+```
+
+### logs
+
+```python
+import logging
+from tgedr_observability.commons import OtlpConfig
+from tgedr_observability.logs import Logs
+
+logs_manager = Logs.instance()
+logs_manager.init(
+  service="orders-service",
+  otlp_config=OtlpConfig(endpoint="http://localhost:4318/v1/logs"),
+)
+
+logger = logging.getLogger(__name__)
+logger.info("orders api started")
+logs_manager.force_flush()
+```
+
+### graceful shutdown
+
+Register app-level shutdown hooks in your entrypoint:
+
+```python
+import atexit
+from tgedr_observability.logs import Logs
+from tgedr_observability.metrics import Metrics
+
+atexit.register(Logs.app_shutdown)
+atexit.register(Metrics.app_shutdown)
+```
+
+## tests and coverage
+
+Run tests:
+
+```bash
+./helper.sh test
+```
+
+Run and print coverage:
+
+```bash
+./helper.sh test_coverage
+```
+
+Current unit tests cover all Python code under `src/`.
+
+
+## observability stack
+
+### VictoriaMetrics
+
+`victoriametrics/victoria-metrics` is the metrics database in this stack. It stores time-series data such as request counts, latency measurements, resource usage, and any custom application metrics sent through OpenTelemetry. In this project, the collector forwards metrics to VictoriaMetrics through its OpenTelemetry ingestion endpoint, and Grafana can then query that stored data for dashboards and operational analysis.
+
+### Loki
+
+`grafana/loki` is the log storage backend. Loki is designed to ingest and organize logs efficiently, making it a good fit for centralizing application and infrastructure logs without the overhead of a heavier full-text indexing platform. Here, the OpenTelemetry collector sends log data to Loki so logs can be explored alongside metrics and traces, which makes it easier to correlate failures, warnings, and service behavior across the same time window.
+
+### Jaeger
+
+`jaegertracing/all-in-one` is the distributed tracing backend. It collects and visualizes traces, which show how a request flows across services and how long each span takes, making it useful for debugging latency and request-path failures. The `all-in-one` image bundles Jaeger's main components into a single container, which keeps this setup simple for local or small-scale environments while still providing a usable trace exploration surface.
+
+## securing the collector
+
+**⚠️ Important: The collector requires a valid Bearer token on every request.** The OTLP HTTP receiver is protected with Bearer token authentication using the OpenTelemetry Collector's `bearertokenauth` extension. Any request to the collector endpoint (`localhost:4318` or the remote endpoint) without an `Authorization: Bearer <token>` header will be rejected with HTTP 401 Unauthorized. This applies to all telemetry data—traces, metrics, and logs.
+
+### configuration
+
+1. **Set the token.** Add a strong random secret to your `.secrets` file (which is git-ignored and loaded by `helper.sh`):
+
+   ```bash
+   export COLLECTOR_TOKEN="$(openssl rand -hex 32)"
+   ```
+
+2. **Rebuild and push the collector image** so the updated config is baked in:
+
+   ```bash
+   ./helper.sh build_push_collector
+   ```
+
+3. **Start the stack.** The `docker-compose.yml` passes `COLLECTOR_TOKEN` through as an environment variable so the collector reads it at runtime:
+
+   ```bash
+   cd docker/observability && docker compose up -d
+   ```
+
+### sending telemetry
+
+**All telemetry ingestion requires the token header.** Any client sending OTLP over HTTP must include the `Authorization: Bearer <token>` header on every call, or the request will be rejected:
+
+```
+Authorization: Bearer <your-token>
+```
+
+**Examples:**
+
+With `telemetrygen` (as used in `helper.sh`):
+
+```bash
+telemetrygen traces --otlp-http \
+  --otlp-header "Authorization=\"Bearer $COLLECTOR_TOKEN\"" \
+  --traces 1
+```
+
+With the OpenTelemetry SDK, configure the exporter headers via the `OTEL_EXPORTER_OTLP_HEADERS` environment variable (applied to all outbound requests):
+
+```bash
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $COLLECTOR_TOKEN"
+```
+
+If the token is missing or invalid, the collector will return `401 Unauthorized`. Verify the token is set correctly in your environment before troubleshooting other issues.

tgedr_observability-0.0.1/README.md

@@ -0,0 +1,222 @@
+# tgedr-observability
+
+![Coverage](./coverage.svg)
+[![PyPI](https://img.shields.io/pypi/v/tgedr-observability)](https://pypi.org/project/tgedr-observability/)
+
+## overview
+
+This repository is an early-stage observability toolkit built around a small Python package and a companion local monitoring stack. The Docker side is the main operational surface: an OpenTelemetry collector receives telemetry and routes metrics, logs, and traces into dedicated backends for storage and analysis. In practice, the project acts as a foundation for collecting, storing, and exploring observability data rather than as a finished application.
+
+## development
+- main requirements:
+  - _uv_  
+  - _bash_
+- Clone the repository like this:
+
+  ``` bash
+  git clone git@github.com:jtviegas/observability
+  ```
+- cd into the folder: `cd observability`
+- install requirements: `./helper.sh reqs`
+
+## source code guide
+
+The Python package lives under `src/tgedr_observability` and currently exposes three modules:
+
+- `commons.py`: shared constants and common types.
+- `metrics.py`: singleton wrapper for OpenTelemetry metrics setup and recording.
+- `logs.py`: singleton wrapper for OpenTelemetry logs setup and recording.
+
+### commons.py
+
+`commons.py` contains:
+
+- `LOCAL_METRICS_URL`: default local OTLP HTTP endpoint for metrics (`http://localhost:4318/v1/metrics`).
+- `OtlpConfig`: dataclass with exporter endpoint and optional headers.
+- `ObservabilityError`: package-specific exception used for observability validation errors.
+
+### metrics.py
+
+`Metrics` is a singleton manager that lazily initializes a global OpenTelemetry `MeterProvider`.
+
+Initialization behavior:
+
+1. `Metrics.instance()` returns the singleton object.
+2. `init(service, otlp_config=None)` configures:
+   - `Resource` with `service.name`.
+   - `ConsoleMetricExporter` (always enabled).
+   - Optional `OTLPMetricExporter` over HTTP when `otlp_config` is passed.
+3. The configured provider is set globally with `metrics.set_meter_provider(provider)`.
+
+Metric naming convention:
+
+- Metric names must have at least two dot-separated parts, for example `orders.api.requests`.
+- Everything before the last segment is used as meter scope name.
+- Last segment is used as instrument name.
+- Invalid names raise `ObservabilityError`.
+
+Instruments managed by the class:
+
+- Counter path: internally uses `create_up_down_counter`.
+- Gauge path: uses `create_gauge` with unit inferred from suffix (`_s` -> `s`, otherwise `1`).
+- Histogram path: uses `create_histogram` with the same unit inference.
+
+Public methods:
+
+- `add_to_counter(name, value, attributes=None)`
+- `add_to_gauge(name, value, attributes=None)`
+- `add_to_histogram(name, value, attributes=None)`
+- `force_flush(timeout_millis=10000)`
+- `shutdown()`
+- `app_shutdown()` (flush + shutdown convenience hook)
+
+### logs.py
+
+`Logs` is a singleton manager that lazily initializes a global OpenTelemetry `LoggerProvider`.
+
+Initialization behavior:
+
+1. `Logs.instance()` returns the singleton object.
+2. `init(service, otlp_config=None)` configures:
+   - `Resource` with `service.name`.
+   - `BatchLogRecordProcessor(ConsoleLogRecordExporter())` (always enabled).
+   - Optional `BatchLogRecordProcessor(OTLPLogExporter(...))` when `otlp_config` is passed.
+3. The provider is set globally with `set_logger_provider(provider)`.
+4. A `LoggingHandler` is attached through `logging.basicConfig(..., force=True)`.
+
+Public methods:
+
+- `force_flush(timeout_millis=10000)`
+- `shutdown()` (also detaches and closes the installed handler)
+- `app_shutdown()` (flush + shutdown convenience hook)
+
+## usage examples
+
+### metrics
+
+```python
+from tgedr_observability.commons import LOCAL_METRICS_URL, OtlpConfig
+from tgedr_observability.metrics import Metrics
+
+metrics_manager = Metrics.instance()
+metrics_manager.init(
+  service="orders-service",
+  otlp_config=OtlpConfig(endpoint=LOCAL_METRICS_URL),
+)
+
+metrics_manager.add_to_counter("orders.api.requests", 1, {"route": "/orders"})
+metrics_manager.add_to_histogram("orders.api.latency_s", 0.123, {"route": "/orders"})
+metrics_manager.force_flush()
+```
+
+### logs
+
+```python
+import logging
+from tgedr_observability.commons import OtlpConfig
+from tgedr_observability.logs import Logs
+
+logs_manager = Logs.instance()
+logs_manager.init(
+  service="orders-service",
+  otlp_config=OtlpConfig(endpoint="http://localhost:4318/v1/logs"),
+)
+
+logger = logging.getLogger(__name__)
+logger.info("orders api started")
+logs_manager.force_flush()
+```
+
+### graceful shutdown
+
+Register app-level shutdown hooks in your entrypoint:
+
+```python
+import atexit
+from tgedr_observability.logs import Logs
+from tgedr_observability.metrics import Metrics
+
+atexit.register(Logs.app_shutdown)
+atexit.register(Metrics.app_shutdown)
+```
+
+## tests and coverage
+
+Run tests:
+
+```bash
+./helper.sh test
+```
+
+Run and print coverage:
+
+```bash
+./helper.sh test_coverage
+```
+
+Current unit tests cover all Python code under `src/`.
+
+
+## observability stack
+
+### VictoriaMetrics
+
+`victoriametrics/victoria-metrics` is the metrics database in this stack. It stores time-series data such as request counts, latency measurements, resource usage, and any custom application metrics sent through OpenTelemetry. In this project, the collector forwards metrics to VictoriaMetrics through its OpenTelemetry ingestion endpoint, and Grafana can then query that stored data for dashboards and operational analysis.
+
+### Loki
+
+`grafana/loki` is the log storage backend. Loki is designed to ingest and organize logs efficiently, making it a good fit for centralizing application and infrastructure logs without the overhead of a heavier full-text indexing platform. Here, the OpenTelemetry collector sends log data to Loki so logs can be explored alongside metrics and traces, which makes it easier to correlate failures, warnings, and service behavior across the same time window.
+
+### Jaeger
+
+`jaegertracing/all-in-one` is the distributed tracing backend. It collects and visualizes traces, which show how a request flows across services and how long each span takes, making it useful for debugging latency and request-path failures. The `all-in-one` image bundles Jaeger's main components into a single container, which keeps this setup simple for local or small-scale environments while still providing a usable trace exploration surface.
+
+## securing the collector
+
+**⚠️ Important: The collector requires a valid Bearer token on every request.** The OTLP HTTP receiver is protected with Bearer token authentication using the OpenTelemetry Collector's `bearertokenauth` extension. Any request to the collector endpoint (`localhost:4318` or the remote endpoint) without an `Authorization: Bearer <token>` header will be rejected with HTTP 401 Unauthorized. This applies to all telemetry data—traces, metrics, and logs.
+
+### configuration
+
+1. **Set the token.** Add a strong random secret to your `.secrets` file (which is git-ignored and loaded by `helper.sh`):
+
+   ```bash
+   export COLLECTOR_TOKEN="$(openssl rand -hex 32)"
+   ```
+
+2. **Rebuild and push the collector image** so the updated config is baked in:
+
+   ```bash
+   ./helper.sh build_push_collector
+   ```
+
+3. **Start the stack.** The `docker-compose.yml` passes `COLLECTOR_TOKEN` through as an environment variable so the collector reads it at runtime:
+
+   ```bash
+   cd docker/observability && docker compose up -d
+   ```
+
+### sending telemetry
+
+**All telemetry ingestion requires the token header.** Any client sending OTLP over HTTP must include the `Authorization: Bearer <token>` header on every call, or the request will be rejected:
+
+```
+Authorization: Bearer <your-token>
+```
+
+**Examples:**
+
+With `telemetrygen` (as used in `helper.sh`):
+
+```bash
+telemetrygen traces --otlp-http \
+  --otlp-header "Authorization=\"Bearer $COLLECTOR_TOKEN\"" \
+  --traces 1
+```
+
+With the OpenTelemetry SDK, configure the exporter headers via the `OTEL_EXPORTER_OTLP_HEADERS` environment variable (applied to all outbound requests):
+
+```bash
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $COLLECTOR_TOKEN"
+```
+
+If the token is missing or invalid, the collector will return `401 Unauthorized`. Verify the token is set correctly in your environment before troubleshooting other issues.

tgedr_observability-0.0.1/pyproject.toml

@@ -0,0 +1,145 @@
+[project]
+name = "tgedr-observability"
+version = "0.0.1"
+description = "simple observability solution"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "opentelemetry-api>=1.44.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.44.0",
+    "opentelemetry-sdk>=1.44.0",
+    "pandas>=2.3.0,<3.0.0",
+    "tgedr-pycommons>=1.2.1",
+]
+
+[[project.authors]]
+name = "developer"
+email = "developer@email.com"
+
+[dependency-groups]
+dev = [
+    "pre-commit~=4.2.0",
+    "pytest~=8.3.5",
+    "pytest-bdd~=8.1.0",
+    "pytest-cov~=4.1.0",
+    "pytest-mock~=3.15.0",
+    "ruff==0.9.10",
+    "bandit==1.8.3",
+    "safety==3.5.1",
+    "typer<0.17.0",
+    "genbadge[coverage]>=1.1.3",
+    "ipykernel>=7.2.0",
+    "jupyter>=1.1.1",
+    "ipywidgets>=8.1.8",
+    "python-dotenv>=1.2.2",
+]
+
+[build-system]
+requires = ["uv-build>=0.6,<1.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tgedr_observability"
+
+[tool.coverage.paths]
+source = ["src/"]
+
+[tool.coverage.run]
+source = ["src/"]
+include = ["src/*"]
+omit = [
+    "*/tests/*",
+    "*/test/*",
+    "*/test_*",
+    "*/__pycache__/*",
+    "*/migrations/*",
+    "*/venv/*",
+    "*/.venv/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+show_missing = true
+skip_covered = false
+skip_empty = false
+
+[tool.pytest.ini_options]
+pythonpath = "."
+
+[tool.ruff]
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+    "tests/",
+    "test/",
+    "typings/",
+    "server/",
+]
+line-length = 120
+indent-width = 4
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D203",
+    "S101",
+    "D104",
+    "INP001",
+    "D213",
+    "COM812",
+    "I001",
+    "D401",
+    "D407",
+    "RET504",
+    "PLR2004",
+    "FA102",
+    "E501",
+    "EXE002",
+    "PLR0913",
+    "PLR0912",
+    "C901",
+    "PLR0911",
+    "G004",
+    "D413",
+    "CPY001",
+]
+fixable = ["ALL"]
+unfixable = []
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"

tgedr_observability-0.0.1/pyproject.toml.orig

@@ -0,0 +1,136 @@
+[project]
+name = "tgedr-observability"
+version = "0.0.1"
+description = "simple observability solution"
+authors = [
+    {name = "developer",email = "developer@email.com"}
+]
+readme = "README.md"
+
+requires-python = ">=3.12,<3.13"
+
+dependencies = [
+    "opentelemetry-api>=1.44.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.44.0",
+    "opentelemetry-sdk>=1.44.0",
+    "pandas>=2.3.0,<3.0.0",
+    "tgedr-pycommons>=1.2.1",
+]
+[dependency-groups]
+dev = [
+    "pre-commit~=4.2.0",
+    "pytest~=8.3.5",
+    "pytest-bdd~=8.1.0",
+    "pytest-cov~=4.1.0",
+    "pytest-mock~=3.15.0",
+    "ruff==0.9.10",
+    "bandit==1.8.3",
+    "safety==3.5.1",
+    "typer<0.17.0",
+    "genbadge[coverage]>=1.1.3",
+    "ipykernel>=7.2.0",
+    "jupyter>=1.1.1",
+    "ipywidgets>=8.1.8",
+    "python-dotenv>=1.2.2",
+]
+
+# [project.scripts]
+# run = "tgedr_pycommons.cicd.entrypoint:entrypoint" 
+
+[build-system]
+requires = ["uv-build>=0.6,<1.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tgedr_observability"
+
+[tool.coverage.paths]
+source = ["src/"]
+
+[tool.coverage.run]
+source = ["src/"]
+include = ["src/*"]
+omit = [
+    "*/tests/*",
+    "*/test/*",
+    "*/test_*",
+    "*/__pycache__/*",
+    "*/migrations/*",
+    "*/venv/*",
+    "*/.venv/*"
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+show_missing = true
+skip_covered = false
+skip_empty = false
+
+[tool.pytest.ini_options]
+# bdd_features_base_dir = "documentation/features"
+pythonpath = "."
+
+
+[tool.ruff]
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+    "tests/",
+    "test/",
+    "typings/",
+    "server/"
+]
+
+line-length = 120
+indent-width = 4
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["D203", "S101", "D104", "INP001", "D213", "COM812", "I001", 
+    "D401", "D407", "RET504", "PLR2004", "FA102", "E501", "EXE002", "PLR0913", 
+    "PLR0912", "C901", "PLR0911", "G004", "D413", "CPY001"]
+fixable = ["ALL"]
+unfixable = []
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"

tgedr_observability-0.0.1/src/tgedr_observability/commons.py

@@ -0,0 +1,15 @@
+"""Common configuration models for observability integrations."""
+
+from dataclasses import dataclass
+
+LOCAL_METRICS_URL: str = "http://localhost:4318/v1/metrics"
+
+
+@dataclass(frozen=True)
+class OtlpConfig:  # noqa: D101
+    endpoint: str
+    headers: dict[str, str] | None = None
+
+
+class ObservabilityError(Exception):
+    """Exception raised for observability-related errors."""

tgedr_observability-0.0.1/src/tgedr_observability/logs.py

@@ -0,0 +1,86 @@
+"""OpenTelemetry logging setup and singleton manager for application logs."""
+
+import logging
+from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import (
+    BatchLogRecordProcessor,
+    ConsoleLogRecordExporter,
+)  # ConsoleLogExporter on versions earlier than 1.39.0
+from opentelemetry._logs import set_logger_provider
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from tgedr_pycommons.utils.singleton import SingletonMeta
+from tgedr_observability.commons import OtlpConfig
+
+
+class Logs(metaclass=SingletonMeta):
+    """Singleton manager for configuring OpenTelemetry logging."""
+
+    @staticmethod
+    def instance() -> "Logs":
+        """Get the singleton instance of the Logs manager."""
+        return Logs()  # pyright: ignore[reportReturnType]
+
+    def __init__(self) -> None:
+        """Initialize the singleton logs manager state."""
+        self._logger_provider: LoggerProvider | None = None
+        self._handler: LoggingHandler | None = None
+
+    def init(self, service: str, otlp_config: OtlpConfig | None = None) -> None:
+        """Initialize the logging provider and configure log exporting."""
+        if self._logger_provider is None:
+            resource = Resource.create(attributes={SERVICE_NAME: service})
+            provider = LoggerProvider(resource=resource)
+            provider.add_log_record_processor(BatchLogRecordProcessor(ConsoleLogRecordExporter()))
+
+            if otlp_config is not None:
+                otlp_exporter = OTLPLogExporter(
+                    endpoint=otlp_config.endpoint,
+                    headers=otlp_config.headers,
+                )
+                provider.add_log_record_processor(BatchLogRecordProcessor(otlp_exporter))
+
+            set_logger_provider(provider)
+
+            handler = LoggingHandler(level=logging.INFO, logger_provider=provider)
+            logging.basicConfig(handlers=[handler], level=logging.INFO, force=True)
+            self._handler = handler
+            self._logger_provider = provider
+
+    def force_flush(self, timeout_millis: int = 10_000) -> bool:
+        """Force export of pending logs from all configured processors."""
+        if self._logger_provider is None:
+            return False
+        return self._logger_provider.force_flush(timeout_millis=timeout_millis)
+
+    def shutdown(self) -> None:
+        """Shut down log processing and detach the OpenTelemetry handler."""
+        if self._logger_provider is None:
+            return
+
+        self._logger_provider.shutdown()
+        self._logger_provider = None
+
+        if self._handler is not None:
+            root_logger = logging.getLogger()
+            root_logger.handlers = [
+                existing_handler for existing_handler in root_logger.handlers if existing_handler is not self._handler
+            ]
+            self._handler.close()
+            self._handler = None
+
+    @staticmethod
+    def app_shutdown() -> None:
+        """Application shutdown hook for logs.
+
+        add shutdownhook to flush and shutdown the logs provider on application exit.
+        ````
+        import atexit
+        atexit.register(Logs.app_shutdown)
+            ````
+        """
+        instance = Logs.instance()
+        if instance._logger_provider is None:  # noqa: SLF001
+            return
+        instance.force_flush()
+        instance.shutdown()

tgedr_observability-0.0.1/src/tgedr_observability/metrics.py

@@ -0,0 +1,140 @@
+"""Metrics manager and helpers for OpenTelemetry instrumentation."""
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+from opentelemetry.metrics import Instrument
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader, ConsoleMetricExporter
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from tgedr_pycommons.utils.singleton import SingletonMeta
+from tgedr_observability.commons import ObservabilityError, OtlpConfig
+
+
+class Metrics(metaclass=SingletonMeta):
+    """Singleton manager for meter creation and metric recording."""
+
+    @staticmethod
+    def instance() -> "Metrics":
+        """Get the singleton instance of the Metrics manager."""
+        return Metrics()  # pyright: ignore[reportReturnType]
+
+    def __init__(self) -> None:
+        """Initialize the singleton metrics manager state."""
+        self._meter_provider: MeterProvider | None = None
+        self._meters: dict[str, metrics.Meter] = {}
+        self._counters: dict[str, metrics.UpDownCounter] = {}
+        self._gauges: dict[str, Instrument] = {}
+        self._histograms: dict[str, metrics.Histogram] = {}
+
+    def init(self, service: str, otlp_config: OtlpConfig | None = None) -> None:
+        """Initialize the metrics provider and configure metric exporting."""
+        if self._meter_provider is None:
+            resource = Resource.create(attributes={SERVICE_NAME: service})
+            readers = []
+            console_exporter = ConsoleMetricExporter()
+            reader_console = PeriodicExportingMetricReader(console_exporter)
+            readers.append(reader_console)
+
+            if otlp_config is not None:
+                http_exporter = OTLPMetricExporter(
+                    endpoint=otlp_config.endpoint,
+                    headers=otlp_config.headers,
+                )
+                reader_http = PeriodicExportingMetricReader(http_exporter, export_interval_millis=5000)
+                readers.append(reader_http)
+
+            provider = MeterProvider(metric_readers=readers, resource=resource)
+            metrics.set_meter_provider(provider)  # Set the global meter provider
+            self._meter_provider = provider
+
+    def _get_meter(self, name: str) -> metrics.Meter:
+        toponomy: list[str] = name.split(".")
+        if len(toponomy) < 2:
+            error_message = "Metric name must have at least two parts separated by '.'"
+            raise ObservabilityError(error_message)
+        meter_name = ".".join(toponomy[:-1])
+
+        if meter_name not in self._meters:
+            self._meters[meter_name] = metrics.get_meter(meter_name)
+        meter = self._meters[meter_name]
+        return meter
+
+    def _get_counter(self, name: str) -> metrics.UpDownCounter:
+        if name not in self._counters:
+            meter = self._get_meter(name)
+            toponomy: list[str] = name.split(".")
+            counter_name = toponomy[-1]
+            self._counters[name] = meter.create_up_down_counter(
+                counter_name, unit="1", description=f"Counter metric for {name}"
+            )
+        return self._counters[name]
+
+    def _get_gauge(self, name: str) -> Instrument:
+        if name not in self._gauges:
+            meter = self._get_meter(name)
+            toponomy: list[str] = name.split(".")
+            gauge_name = toponomy[-1]
+            gauge_type = "s" if gauge_name[-2:] == "_s" else "1"
+            self._gauges[name] = meter.create_gauge(gauge_name, unit=gauge_type, description=f"Gauge metric for {name}")
+        return self._gauges[name]
+
+    def _get_histogram(self, name: str) -> metrics.Histogram:
+        if name not in self._histograms:
+            meter = self._get_meter(name)
+            toponomy: list[str] = name.split(".")
+            histogram_name = toponomy[-1]
+            histogram_type = "s" if histogram_name[-2:] == "_s" else "1"
+            self._histograms[name] = meter.create_histogram(
+                histogram_name, unit=histogram_type, description=f"Histogram metric for {name}"
+            )
+        return self._histograms[name]
+
+    def add_to_counter(self, name: str, value: int, attributes: dict[str, str] | None = None) -> None:
+        """Add a value to the named counter metric."""
+        counter = self._get_counter(name)
+        counter.add(value, attributes=attributes)
+
+    def add_to_gauge(self, name: str, value: float, attributes: dict[str, str] | None = None) -> None:
+        """Add a value to the named gauge metric."""
+        gauge = self._get_gauge(name)
+        gauge.set(value, attributes=attributes)  # pyright: ignore[reportAttributeAccessIssue]
+
+    def add_to_histogram(self, name: str, value: float, attributes: dict[str, str] | None = None) -> None:
+        """Add a value to the named histogram metric."""
+        histogram = self._get_histogram(name)
+        histogram.record(value, attributes=attributes)
+
+    def force_flush(self, timeout_millis: int = 10_000) -> bool:
+        """Force export of pending metrics from all configured readers."""
+        if self._meter_provider is None:
+            error_message = "Metrics provider is not initialized. Call init() first."
+            raise ObservabilityError(error_message)
+        return self._meter_provider.force_flush(timeout_millis=timeout_millis)
+
+    def shutdown(self) -> None:
+        """Shut down the metrics pipeline and clear cached instruments."""
+        if self._meter_provider is None:
+            return
+
+        self._meter_provider.shutdown()
+        self._meter_provider = None
+        self._meters.clear()
+        self._counters.clear()
+        self._gauges.clear()
+        self._histograms.clear()
+
+    @staticmethod
+    def app_shutdown() -> None:
+        """Application shutdown hook for metrics.
+
+        add shutdownhook to flush and shutdown the metrics provider on application exit.
+        ````
+        import atexit
+        atexit.register(Metrics.app_shutdown)
+        ````
+        """
+        instance = Metrics.instance()
+        if instance._meter_provider is None:  # noqa: SLF001
+            return
+        instance.force_flush()
+        instance.shutdown()