From d0ddc0ca0360c04e2cd7b42a114cba7cc4d4877d Mon Sep 17 00:00:00 2001 From: Dwi Fahni Denni Date: Sat, 30 May 2026 14:05:09 +0700 Subject: [PATCH] fix: Verified zero vulnerabilities (CRITICAL/HIGH/MEDIUM) across all targets using Trivy v0.70.0 --- .dockerignore | 2 +- CHANGELOG.md | 6 +++++ Dockerfile | 7 +++--- docs/ARCHITECTURE.md | 48 +++++++++++++++++++------------------- docs/BUILD-SYSTEM.md | 1 + docs/GENERATOR.md | 54 +++++++++++++++++++++++-------------------- docs/QUICKSTART.md | 15 +++++++----- docs/README.md | 55 ++++++++++++++++++++++++-------------------- 8 files changed, 103 insertions(+), 85 deletions(-) diff --git a/.dockerignore b/.dockerignore index 5c0d91d..883dbf2 100644 --- a/.dockerignore +++ b/.dockerignore @@ -105,4 +105,4 @@ docker-compose*.yml # Documentation files *.md !README.md -LICENSE +!LICENSE diff --git a/CHANGELOG.md b/CHANGELOG.md index a174f3c..3f1a6a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -123,6 +123,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Version Alignment (CVS)**: Fixed `version.py` from stale `1.1.1` to `1.2.0` matching `pyproject.toml` and `CHANGELOG.md` - **Version Alignment (CVS)**: Updated `Dockerfile` `ARG VERSION` and OCI labels from `1.1.1` to `1.2.0` - **Version Alignment (CVS)**: Updated `Dockerfile` build comments from `1.1.1` to `1.2.0` +- **Docker Build Fix - .dockerignore**: Fixed `.dockerignore` excluding `LICENSE` file from Docker build context — changed from `LICENSE` to `!LICENSE` so the multi-stage `Dockerfile` can successfully `COPY LICENSE` +- **Docker Build Fix - Shell Compatibility**: Fixed `Dockerfile` builder stage using bash process substitution `<()` which is unsupported in `/bin/sh` — replaced with POSIX-compliant `printf > /tmp/reqs.txt` approach for pip wheel requirements +- **Security - Trivy Vulnerability Scan**: Verified zero vulnerabilities (CRITICAL/HIGH/MEDIUM) across all targets using Trivy v0.70.0: + - Source code filesystem scan: **0 vulnerabilities** + - Production Docker image (`python:3.14-slim` / Debian 13.5): **0 vulnerabilities** + - Development Docker image (`python:3.14-slim` / Debian 13.5): **0 vulnerabilities** ### SDK Configuration Structure diff --git a/Dockerfile b/Dockerfile index 057b4a6..e1d19be 100644 --- a/Dockerfile +++ b/Dockerfile @@ -55,10 +55,9 @@ COPY src/ ./src/ # Build the wheel package RUN pip install --upgrade pip build && \ python -m build --wheel && \ - pip wheel --wheel-dir=/wheels -r <(echo "opentelemetry-api>=1.28.0" && \ - echo "opentelemetry-sdk>=1.28.0" && \ - echo "opentelemetry-exporter-otlp-proto-grpc>=1.28.0" && \ - echo "opentelemetry-exporter-otlp-proto-http>=1.28.0") + printf 'opentelemetry-api>=1.28.0\nopentelemetry-sdk>=1.28.0\nopentelemetry-exporter-otlp-proto-grpc>=1.28.0\nopentelemetry-exporter-otlp-proto-http>=1.28.0\n' > /tmp/reqs.txt && \ + pip wheel --wheel-dir=/wheels -r /tmp/reqs.txt && \ + rm -f /tmp/reqs.txt # ----------------------------------------------------------------------------- # Stage 2: Runtime diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 32ed282..7c81ca7 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -76,12 +76,12 @@ graph TB The SDK follows DDD tactical patterns: -| Pattern | Implementation | Purpose | -|---------|---------------|---------| +| Pattern | Implementation | Purpose | +| ------------------ | ----------------- | ------------------------------ | | **Aggregate Root** | `TelemetryConfig` | Encapsulates all configuration | -| **Value Object** | `Credentials` | Immutable API key pair | -| **Entity** | N/A | Not needed for SDK use case | -| **Repository** | N/A | Telemetry is write-only | +| **Value Object** | `Credentials` | Immutable API key pair | +| **Entity** | N/A | Not needed for SDK use case | +| **Repository** | N/A | Telemetry is write-only | ### 2. CQRS Pattern @@ -658,13 +658,13 @@ flowchart TB ### Validation Points -| Layer | Validation | Error Type | -|-------|------------|------------| -| Domain | Credentials format | `CredentialsError` | -| Domain | Config completeness | `ConfigError` | -| Builder | Required fields | `BuilderError` | -| Client | Initialization state | `NotInitializedError` | -| Infrastructure | Export errors | Logged, may retry | +| Layer | Validation | Error Type | +| -------------- | -------------------- | --------------------- | +| Domain | Credentials format | `CredentialsError` | +| Domain | Config completeness | `ConfigError` | +| Builder | Required fields | `BuilderError` | +| Client | Initialization state | `NotInitializedError` | +| Infrastructure | Export errors | Logged, may retry | ## Thread Safety @@ -692,12 +692,12 @@ graph TB ### Thread Safety Mechanisms -| Component | Mechanism | Protected Operations | -|-----------|-----------|---------------------| -| Client | `RLock` | initialize, shutdown | -| Handler | `RLock` | initialization state | -| Active Spans | `Lock` | span tracking dict | -| Instruments | `Lock` | metric instruments cache | +| Component | Mechanism | Protected Operations | +| ------------ | --------- | ------------------------ | +| Client | `RLock` | initialize, shutdown | +| Handler | `RLock` | initialization state | +| Active Spans | `Lock` | span tracking dict | +| Instruments | `Lock` | metric instruments cache | ## Extension Points @@ -766,12 +766,12 @@ mindmap ### Configuration Tuning -| Parameter | Default | Tuning Guide | -|-----------|---------|--------------| -| `batch_timeout` | 10s | Lower for real-time, higher for efficiency | -| `batch_max_size` | 512 | Higher for throughput, lower for latency | -| `timeout` | 30s | Based on network conditions | -| `compression` | true | Disable for low CPU environments | +| Parameter | Default | Tuning Guide | +| ---------------- | ------- | ------------------------------------------ | +| `batch_timeout` | 10s | Lower for real-time, higher for efficiency | +| `batch_max_size` | 512 | Higher for throughput, lower for latency | +| `timeout` | 30s | Based on network conditions | +| `compression` | true | Disable for low CPU environments | ## Best Practices diff --git a/docs/BUILD-SYSTEM.md b/docs/BUILD-SYSTEM.md index 12bc9e6..3d5856c 100644 --- a/docs/BUILD-SYSTEM.md +++ b/docs/BUILD-SYSTEM.md @@ -331,6 +331,7 @@ make build ``` Creates: + - `dist/telemetryflow_python_sdk-1.2.0-py3-none-any.whl` - `dist/telemetryflow_python_sdk-1.2.0.tar.gz` diff --git a/docs/GENERATOR.md b/docs/GENERATOR.md index 1d977d7..8be475c 100644 --- a/docs/GENERATOR.md +++ b/docs/GENERATOR.md @@ -35,11 +35,11 @@ graph TB ### Overview -| Command | Description | -|---------|-------------| -| `init` | Initialize TelemetryFlow in your project | -| `example` | Generate example code | -| `version` | Show version information | +| Command | Description | +| --------- | ---------------------------------------- | +| `init` | Initialize TelemetryFlow in your project | +| `example` | Generate example code | +| `version` | Show version information | ## Command: init @@ -53,17 +53,17 @@ telemetryflow-gen init [options] ### Options -| Option | Short | Default | Description | -|--------|-------|---------|-------------| -| `--output` | `-o` | `.` | Output directory | -| `--force` | `-f` | `false` | Overwrite existing files | +| Option | Short | Default | Description | +| ---------- | ----- | ------- | ------------------------ | +| `--output` | `-o` | `.` | Output directory | +| `--force` | `-f` | `false` | Overwrite existing files | ### Output Files -| File | Description | -|------|-------------| -| `.env.telemetryflow` | Environment configuration template | -| `telemetryflow_example.py` | Basic usage example | +| File | Description | +| -------------------------- | ---------------------------------- | +| `.env.telemetryflow` | Environment configuration template | +| `telemetryflow_example.py` | Basic usage example | ### Example @@ -146,17 +146,17 @@ telemetryflow-gen example [options] ### Options -| Option | Short | Default | Description | -|--------|-------|---------|-------------| -| `--type` | `-t` | `basic` | Example type | -| `--output` | `-o` | `.` | Output directory | -| `--force` | `-f` | `false` | Overwrite existing files | +| Option | Short | Default | Description | +| ---------- | ----- | ------- | ------------------------ | +| `--type` | `-t` | `basic` | Example type | +| `--output` | `-o` | `.` | Output directory | +| `--force` | `-f` | `false` | Overwrite existing files | ### Example Types -| Type | Description | Output File | -|------|-------------|-------------| -| `basic` | Basic SDK usage | `basic_example.py` | +| Type | Description | Output File | +| ------------- | -------------------------------- | ------------------------ | +| `basic` | Basic SDK usage | `basic_example.py` | | `http-server` | HTTP server with instrumentation | `http_server_example.py` | ### Example @@ -175,6 +175,7 @@ telemetryflow-gen example -t http-server -o ./examples ### Basic Example Template The basic example demonstrates: + - Client initialization and shutdown - Recording metrics (counter, gauge, histogram) - Emitting logs (info, warn, error, debug) @@ -185,6 +186,7 @@ The basic example demonstrates: ### HTTP Server Example Template The HTTP server example demonstrates: + - Full request instrumentation - Automatic span creation for requests - Request duration histogram @@ -262,11 +264,13 @@ TELEMETRYFLOW_SERVICE_NAME=your-service-name ### Step 3: Load Environment Option A: Source the file: + ```bash source .env.telemetryflow ``` Option B: Use python-dotenv: + ```python from dotenv import load_dotenv load_dotenv('.env.telemetryflow') @@ -378,10 +382,10 @@ def main(argv: list[str] | None = None) -> int: ### Exit Codes -| Code | Description | -|------|-------------| -| 0 | Success | -| 1 | Error (file exists, invalid option, etc.) | +| Code | Description | +| ---- | ----------------------------------------- | +| 0 | Success | +| 1 | Error (file exists, invalid option, etc.) | ## Related Documentation diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index eb43145..81a8e44 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -161,13 +161,13 @@ else: ## Span Kinds -| Kind | Use Case | -|------|----------| +| Kind | Use Case | +| ------------------- | ----------------------------- | | `SpanKind.INTERNAL` | Internal operations (default) | -| `SpanKind.SERVER` | Server-side request handling | -| `SpanKind.CLIENT` | Client-side requests | -| `SpanKind.PRODUCER` | Message queue producers | -| `SpanKind.CONSUMER` | Message queue consumers | +| `SpanKind.SERVER` | Server-side request handling | +| `SpanKind.CLIENT` | Client-side requests | +| `SpanKind.PRODUCER` | Message queue producers | +| `SpanKind.CONSUMER` | Message queue consumers | ## Data Flow @@ -204,6 +204,7 @@ Error: Failed to connect to api.telemetryflow.id:4317 ``` **Solutions:** + 1. Check your network connectivity 2. Verify the endpoint is correct 3. Try using HTTP protocol: `.with_http()` @@ -215,6 +216,7 @@ Error: API key ID must start with 'tfk_' ``` **Solutions:** + 1. Verify your API key format 2. Ensure environment variables are set correctly 3. Check for trailing whitespace in credentials @@ -226,5 +228,6 @@ NotInitializedError: Client is not initialized. Call initialize() first. ``` **Solutions:** + 1. Call `client.initialize()` before using the client 2. Use the context manager pattern: `with ... as client:` diff --git a/docs/README.md b/docs/README.md index b7bd927..dbd3d06 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,14 +4,14 @@ Welcome to the TelemetryFlow Python SDK documentation. This SDK provides a simpl ## Documentation Index -| Document | Description | -|----------|-------------| -| [Quick Start](QUICKSTART.md) | Get started in 5 minutes | -| [Architecture](ARCHITECTURE.md) | DDD/CQRS architecture with diagrams | -| [API Reference](API_REFERENCE.md) | Complete API documentation | -| [Generator](GENERATOR.md) | CLI generator tool | -| [Testing](TESTING.md) | Testing guide and best practices | -| [Build System](BUILD-SYSTEM.md) | Build system and development | +| Document | Description | +| --------------------------------- | ----------------------------------- | +| [Quick Start](QUICKSTART.md) | Get started in 5 minutes | +| [Architecture](ARCHITECTURE.md) | DDD/CQRS architecture with diagrams | +| [API Reference](API_REFERENCE.md) | Complete API documentation | +| [Generator](GENERATOR.md) | CLI generator tool | +| [Testing](TESTING.md) | Testing guide and best practices | +| [Build System](BUILD-SYSTEM.md) | Build system and development | ## Quick Links @@ -62,27 +62,30 @@ graph TB ## SDK Features ### Core Features + - **100% OTLP Compliant**: Full OpenTelemetry Protocol support - **Three Signals**: Metrics, Logs, and Traces - **Multiple Protocols**: gRPC (default) and HTTP - **Type Safety**: Full type hints with mypy support ### Architecture + - **Domain-Driven Design (DDD)**: Clean separation of concerns - **CQRS Pattern**: Command Query Responsibility Segregation - **Builder Pattern**: Fluent configuration API - **Immutable Value Objects**: Thread-safe credentials ### Integrations + - **Flask Middleware**: Automatic HTTP instrumentation - **FastAPI Middleware**: ASGI middleware support - **CLI Generator**: Project scaffolding tool ## Supported Python Versions -| Version | Status | -|---------|--------| -| Python 3.9 | ✅ Supported | +| Version | Status | +| ----------- | ------------ | +| Python 3.9 | ✅ Supported | | Python 3.10 | ✅ Supported | | Python 3.11 | ✅ Supported | | Python 3.12 | ✅ Supported | @@ -91,22 +94,24 @@ graph TB ## Dependencies ### Core Dependencies -| Package | Version | Purpose | -|---------|---------|---------| -| opentelemetry-api | ≥1.28.0 | Core telemetry API | -| opentelemetry-sdk | ≥1.28.0 | SDK implementation | -| opentelemetry-exporter-otlp-proto-grpc | ≥1.28.0 | gRPC exporter | -| opentelemetry-exporter-otlp-proto-http | ≥1.28.0 | HTTP exporter | + +| Package | Version | Purpose | +| -------------------------------------- | ------- | ------------------ | +| opentelemetry-api | ≥1.28.0 | Core telemetry API | +| opentelemetry-sdk | ≥1.28.0 | SDK implementation | +| opentelemetry-exporter-otlp-proto-grpc | ≥1.28.0 | gRPC exporter | +| opentelemetry-exporter-otlp-proto-http | ≥1.28.0 | HTTP exporter | ### Optional Dependencies -| Package | Group | Purpose | -|---------|-------|---------| -| flask | http | Flask middleware | -| fastapi | http | FastAPI middleware | -| grpcio | grpc | gRPC support | -| pytest | dev | Testing framework | -| mypy | dev | Type checking | -| ruff | dev | Linting | + +| Package | Group | Purpose | +| ------- | ----- | ------------------ | +| flask | http | Flask middleware | +| fastapi | http | FastAPI middleware | +| grpcio | grpc | gRPC support | +| pytest | dev | Testing framework | +| mypy | dev | Type checking | +| ruff | dev | Linting | ## Getting Help