Skip to content

CHANGELOG.md

Latest commit

 

History

History
253 lines (206 loc) · 12.9 KB

CHANGELOG.md

File metadata and controls

253 lines (206 loc) · 12.9 KB
TelemetryFlow Logo

TelemetryFlow Python SDK

Version License Python PyPI OTEL SDK OpenTelemetry Docker

Enterprise-grade Python SDK for TelemetryFlow - the observability platform that provides unified metrics, logs, and traces collection following OpenTelemetry standards.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.2.0] - 2025-05-27

Added

  • Dependabot Configuration: Added .github/dependabot.yml for automated dependency updates (pip, docker, github-actions ecosystems)

Changed

  • OpenTelemetry SDK Dependency: Upgraded minimum OTEL SDK from >=1.28.0 to >=1.42.1 in pyproject.toml
  • OpenTelemetry Instrumentation: Upgraded minimum instrumentation from >=0.49b0 to >=0.63b1 in pyproject.toml
  • GitHub Actions CI/CD: Upgraded all workflow action versions
    • actions/checkout v4 → v6
    • actions/upload-artifact v4 → v7
    • actions/download-artifact v4 → v8
    • docker/metadata-action v5 → v6
    • docker/setup-qemu-action v3 → v4
    • docker/setup-buildx-action v3 → v4
    • docker/login-action v3 → v4
    • docker/build-push-action v6 → v7
    • softprops/action-gh-release v2 → v3
  • TFO-Collector Version: Updated CI reference from v1.1.2 to v1.2.1
  • Docker Compose: Removed Grafana and Jaeger services; added TFO Platform services (tfo-backend, tfo-viz, postgres, clickhouse, redis, nats) under platform profile
  • File Headers: Refactored all 66 Python source files to standard Apache 2.0 license header format

Added

  • Build Package in Dev Dependencies: Added build>=1.0.0 to dev dependencies for local package building

  • gRPC Header Lowercase Support: Added _get_grpc_headers() method in OTLPExporterFactory to ensure gRPC metadata keys are lowercase (required by gRPC specification)

  • Comprehensive Unit Tests: Added TestGetGrpcHeaders test class for gRPC header handling

  • TFO v2 API Configuration Alignment: Updated SDK configuration to align with TFO-Collector v1.2.1

    • Added v2_api configuration section with enabled and v2_only options
    • Added custom endpoint paths support (traces_endpoint, metrics_endpoint, logs_endpoint)
    • Aligned with tfoexporter component for consistent API versioning

  • Collector Identity Support: Added collector identity configuration aligned with tfoidentityextension

    • Collector ID, name, description, hostname, and datacenter settings
    • Custom tags support for collector identification
    • Resource attribute enrichment toggle

  • SDK Configuration Files: Added default configuration files for different use cases

    • configs/sdk-default.yaml - Full SDK configuration with all options
    • configs/sdk-v2-only.yaml - Production-optimized v2-only mode
    • configs/sdk-minimal.yaml - Quick-start minimal configuration

  • Enhanced Environment Variables: Updated .env.example with TFO v2 API settings

    • TELEMETRYFLOW_USE_V2_API - Enable/disable v2 API endpoints
    • TELEMETRYFLOW_V2_ONLY - Enable v2-only mode
    • TELEMETRYFLOW_COLLECTOR_NAME - Human-readable collector name
    • TELEMETRYFLOW_DATACENTER - Datacenter/region identifier
    • TELEMETRYFLOW_ENRICH_RESOURCES - Resource attribute enrichment

  • Command Generator Updates: Updated telemetryflow-gen CLI with TFO v2 API support

    • Added --use-v2-api, --v2-only, --collector-name, --datacenter, --protocol CLI options
    • Updated TemplateData class with TFO v2 API fields
    • Updated all templates (env.tpl, init.py.tpl, example_basic.py.tpl, README.md.tpl) for v2 API
    • Added init_v2_only() convenience function in generated code
    • Templates now include SDK version and TFO-Collector version metadata

  • Unit Tests: Added comprehensive unit tests for TFO v2 API features

    • Tests for TemplateData v2 API fields and serialization
    • Tests for CLI v2 API options (--v2-only, --collector-name, etc.)
    • Tests for template rendering with v2 API variables

  • Examples: Updated examples with TFO v2 API documentation

    • Updated examples/basic/main.py with v2 API usage

Changed

  • CI Python Version Matrix: Updated CI workflow to test on Python 3.12 and 3.13 only (aligned with requires-python = ">=3.12")
  • Updated version to 1.2.0 to align with TFO-Collector v1.2.1 release
  • Default endpoint changed from api.telemetryflow.id:4317 to localhost:4317 for development
  • Added TELEMETRYFLOW_PROTOCOL and TELEMETRYFLOW_TIMEOUT environment variables

Fixed

  • gRPC Header Case Sensitivity: Fixed gRPC exporter to use lowercase header keys (gRPC metadata specification requires lowercase keys)
  • Security - Credentials Exposure: Removed partial API key secret leak in Credentials.__str__() — now masks secret completely with *** instead of exposing first 8 characters
  • Security - Plaintext Secret Header: Removed X-TelemetryFlow-Key-Secret from auth_headers() — API key secret is now only transmitted via the Authorization header
  • Security - Endpoint SSRF Validation: Added regex-based host:port validation in TelemetryConfig._validate() to prevent Server-Side Request Forgery via malformed endpoints
  • Security - Insecure TLS Warning: Added logging.warning() when with_insecure(True) is called to alert developers that TLS is disabled
  • Security - Hardcoded Secrets: Removed all hardcoded default passwords from docker-compose.yml — PostgreSQL, ClickHouse, JWT, and session secrets now require explicit configuration via ${VAR:?msg} pattern
  • Security - CORS Wildcard: Changed default CORS_ORIGIN from * to http://localhost:8080 in docker-compose.yml and .env.example
  • Security - Weak Defaults: Removed weak default secrets (change-me-in-production, telemetryflow123) from .env.example — all secret fields now empty by default
  • Security - Insecure Default: Changed TELEMETRYFLOW_INSECURE default from true to false in .env.example with security warning
  • Security - Docker Root User: Added non-root telemetryflow user (UID 10001) to Dockerfile.dev with USER directive
  • Security - Docker CVE Hardening: Updated Dockerfile, Dockerfile.dev, and docker.yml workflow to patch Trivy-detected CVEs:
    • apt-get upgrade -y to patch ncurses, glibc, util-linux, xz, zlib, tar, systemd, sqlite vulnerabilities
    • Removed perl package to eliminate Archive::Tar, IO::Compress, IO::Uncompress::Unzip CVEs
    • Upgraded pip to latest version to fix arbitrary code execution, path traversal, and improper archive handling
  • 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

# TFO v2 API Configuration
v2_api:
  enabled: true
  v2_only: false
  traces_endpoint: "/v2/traces"
  metrics_endpoint: "/v2/metrics"
  logs_endpoint: "/v2/logs"

# Collector Identity
collector:
  id: "${TELEMETRYFLOW_COLLECTOR_ID:}"
  name: "TelemetryFlow Python SDK"
  datacenter: "default"
  enrich_resources: true
  tags:
    sdk_version: "1.2.0"
    sdk_language: "python"

[1.1.1] - 2024-12-30

Added

  • Dual Endpoint Ingestion Support: Updated docker-compose and OTEL collector configs for TFO-Collector dual ingestion
    • v1 endpoints: Standard OTEL community format (/v1/traces, /v1/metrics, /v1/logs)
    • v2 endpoints: TelemetryFlow enhanced format (/v2/traces, /v2/metrics, /v2/logs)
    • gRPC endpoint: Same port (4317) for both v1 and v2
  • TFO-Collector as Default: Docker-compose now uses telemetryflow/telemetryflow-collector as default image
    • Commented alternatives for TFO-Collector-OCB and OTEL Collector Contrib
    • Separate volume mounts for each collector type
  • Enhanced Port Configuration: Added additional ports for observability
    • zPages (55679) for debugging
    • pprof (1777) for profiling
    • Prometheus exporter (8889)
  • Connectors for Exemplars: Added spanmetrics and servicegraph connectors
    • Metrics-to-traces correlation with exemplars enabled
    • Service dependency graph generation
  • Template-based code generation for telemetryflow-gen CLI
  • Template-based code generation for telemetryflow-restapi CLI
  • External .tpl template files for all generated code
  • --template-dir CLI option for custom templates
  • Comprehensive unit tests for CLI generators

Changed

  • Refactored generator.py to use external template files (reduced inline code by ~70%)
  • Refactored generator_restapi.py to use external template files (reduced from 2326 to 843 lines)
  • Templates now loaded via importlib.resources for package portability
  • Improved template organization with subdirectories (project, infrastructure, domain, application, entity)

Template Structure

templates/
├── native/                    # telemetryflow-gen templates
│   ├── env.tpl
│   ├── init.py.tpl
│   ├── metrics.py.tpl
│   ├── logs.py.tpl
│   ├── traces.py.tpl
│   ├── README.md.tpl
│   └── example_*.py.tpl
└── restapi/                   # telemetryflow-restapi templates
    ├── project/               # Project scaffolding
    ├── infrastructure/        # Infrastructure layer
    ├── domain/                # Domain layer (DDD)
    ├── application/           # Application layer (CQRS)
    └── entity/                # Entity CRUD generation

[1.1.0] - 2024-12-29

Added

  • Initial release of TelemetryFlow Python SDK
  • Full OpenTelemetry support with OTLP export
  • Metrics support (counter, gauge, histogram)
  • Logs support with severity levels
  • Traces support with span management
  • gRPC and HTTP protocol support
  • Builder pattern for client configuration
  • Environment variable configuration
  • Flask middleware integration
  • FastAPI middleware integration
  • CLI generator for project scaffolding
  • Comprehensive test suite
  • Type hints with mypy support
  • DDD architecture with CQRS pattern

Features

  • TelemetryFlowClient - Main SDK client
  • TelemetryFlowBuilder - Fluent configuration builder
  • Credentials - Immutable API key value object
  • TelemetryConfig - Configuration aggregate root
  • Framework middleware for Flask and FastAPI
  • Context manager support for spans
  • Exemplars support for metrics-to-traces correlation
  • Collector ID and service namespace support
  • Custom resource attributes

Documentation

  • Comprehensive README with examples
  • API reference documentation
  • Integration guides
  • Example applications (basic, HTTP server, worker, gRPC)

Planned

  • AsyncIO support
  • Django middleware
  • Batch log emission
  • More framework integrations