Refactoring TFO-Python-SDK for adopting TFO-Collector v1.1.2 Native OCB

Author: zeroc0d3

.env.example

@@ -1,95 +1,148 @@
 # =============================================================================
-# TelemetryFlow Python SDK - Environment Variables
+# TelemetryFlow Python SDK - Environment Configuration
 # =============================================================================
-# Copy this file to .env and update the values as needed
+# Copy this file to .env and update the values
+# Compatible with TFO-Collector v1.1.2 (OCB-native)
 # =============================================================================
 
 # -----------------------------------------------------------------------------
-# Build Configuration
+# SDK VERSION
 # -----------------------------------------------------------------------------
-VERSION=1.1.1
-GIT_COMMIT=unknown
+VERSION=1.1.2
+GIT_COMMIT=
 GIT_BRANCH=main
-BUILD_TIME=unknown
+BUILD_TIME=
 
 # -----------------------------------------------------------------------------
-# TelemetryFlow API Credentials
+# DOCKER IMAGES
 # -----------------------------------------------------------------------------
-# Get your API keys from https://app.telemetryflow.id
+IMAGE_NAME=telemetryflow/telemetryflow-python-sdk
+IMAGE_TAG=1.1.2
 
-TELEMETRYFLOW_API_KEY_ID=tfk_your_key_id
-TELEMETRYFLOW_API_KEY_SECRET=tfs_your_key_secret
+# Container names
+CONTAINER_NAME=telemetryflow-python-sdk
+CONTAINER_NAME_RESTAPI=telemetryflow-python-restapi
 
 # -----------------------------------------------------------------------------
-# Service Configuration
+# OPENTELEMETRY COLLECTOR
 # -----------------------------------------------------------------------------
-# Unique name for your service
-TELEMETRYFLOW_SERVICE_NAME=my-python-service
+OTEL_VERSION=0.142.0
+TFO_COLLECTOR_VERSION=1.1.2
 
-# Service version (semver recommended)
-TELEMETRYFLOW_SERVICE_VERSION=1.0.0
+# Collector ports
+OTLP_GRPC_PORT=4317
+OTLP_HTTP_PORT=4318
+OTEL_METRICS_PORT=8888
+OTEL_HEALTH_PORT=13133
 
-# Service namespace for multi-tenant support
-TELEMETRYFLOW_SERVICE_NAMESPACE=telemetryflow
+# -----------------------------------------------------------------------------
+# JAEGER (Tracing)
+# -----------------------------------------------------------------------------
+JAEGER_UI_PORT=16686
+JAEGER_HTTP_PORT=14268
+JAEGER_GRPC_PORT=14250
 
 # -----------------------------------------------------------------------------
-# Connection Settings
+# PROMETHEUS (Metrics)
 # -----------------------------------------------------------------------------
-# OTLP collector endpoint
-TELEMETRYFLOW_ENDPOINT=api.telemetryflow.id:4317
+PROMETHEUS_PORT=9090
 
-# Use insecure connection (for local development)
-TELEMETRYFLOW_INSECURE=false
+# -----------------------------------------------------------------------------
+# GRAFANA (Dashboards)
+# -----------------------------------------------------------------------------
+GRAFANA_PORT=3000
+GRAFANA_USER=admin
+GRAFANA_PASSWORD=admin
 
-# Deployment environment (production, staging, development)
+# -----------------------------------------------------------------------------
+# TELEMETRYFLOW SDK - Core Settings
+# -----------------------------------------------------------------------------
+TELEMETRYFLOW_API_KEY_ID=tfk_your_key_id
+TELEMETRYFLOW_API_KEY_SECRET=tfs_your_key_secret
+TELEMETRYFLOW_ENDPOINT=localhost:4317
+TELEMETRYFLOW_SERVICE_NAME=my-service
+TELEMETRYFLOW_SERVICE_VERSION=1.1.2
+TELEMETRYFLOW_SERVICE_NAMESPACE=telemetryflow
 TELEMETRYFLOW_ENVIRONMENT=development
+TELEMETRYFLOW_INSECURE=true
 
 # -----------------------------------------------------------------------------
-# Collector Configuration
+# TELEMETRYFLOW SDK - TFO v2 API Settings (aligned with tfoexporter)
 # -----------------------------------------------------------------------------
-# Unique collector ID for distributed collectors
-# TELEMETRYFLOW_COLLECTOR_ID=collector-001
+# Enable TFO v2 API (default: true)
+TELEMETRYFLOW_USE_V2_API=true
 
-# TelemetryFlow backend (if using local collector)
-# TELEMETRYFLOW_API_ENDPOINT=http://localhost:3100
+# Enable v2-only mode - disables v1 endpoints (default: false)
+TELEMETRYFLOW_V2_ONLY=false
 
-# Tenant and workspace (for multi-tenant deployments)
-# TELEMETRYFLOW_TENANT_ID=default
-# TELEMETRYFLOW_WORKSPACE_ID=default
+# Custom endpoint paths (defaults to v2 when USE_V2_API=true)
+# TELEMETRYFLOW_TRACES_ENDPOINT=/v2/traces
+# TELEMETRYFLOW_METRICS_ENDPOINT=/v2/metrics
+# TELEMETRYFLOW_LOGS_ENDPOINT=/v2/logs
 
 # -----------------------------------------------------------------------------
-# Telemetry Feature Flags
+# TELEMETRYFLOW SDK - Collector Identity (aligned with tfoidentityextension)
 # -----------------------------------------------------------------------------
-TELEMETRYFLOW_ENABLE_METRICS=true
-TELEMETRYFLOW_ENABLE_LOGS=true
-TELEMETRYFLOW_ENABLE_TRACES=true
+TELEMETRYFLOW_COLLECTOR_ID=
+TELEMETRYFLOW_COLLECTOR_NAME=TelemetryFlow Python SDK
+TELEMETRYFLOW_COLLECTOR_HOSTNAME=
+TELEMETRYFLOW_DATACENTER=default
+
+# Enable resource enrichment (default: true)
+TELEMETRYFLOW_ENRICH_RESOURCES=true
 
 # -----------------------------------------------------------------------------
-# Batch Processing Configuration
+# TELEMETRYFLOW SDK - Protocol Settings
 # -----------------------------------------------------------------------------
-TELEMETRYFLOW_BATCH_SIZE=512
-TELEMETRYFLOW_BATCH_TIMEOUT=5s
+# Protocol: grpc or http (default: grpc)
+TELEMETRYFLOW_PROTOCOL=grpc
+
+# Enable compression (default: false)
+TELEMETRYFLOW_COMPRESSION=false
+
+# Timeout in seconds (default: 10)
+TELEMETRYFLOW_TIMEOUT=10
 
 # -----------------------------------------------------------------------------
-# Network Configuration (for local development)
+# TELEMETRYFLOW SDK - Retry Settings
 # -----------------------------------------------------------------------------
-# OTLP gRPC receiver port
-OTLP_GRPC_PORT=4317
+# Enable retry (default: true)
+TELEMETRYFLOW_RETRY_ENABLED=true
 
-# OTLP HTTP receiver port
-OTLP_HTTP_PORT=4318
+# Max retries (default: 3)
+TELEMETRYFLOW_MAX_RETRIES=3
 
-# Prometheus metrics port (self-observability)
-METRICS_PORT=8888
+# Retry backoff in milliseconds (default: 500)
+TELEMETRYFLOW_RETRY_BACKOFF=500
 
-# Prometheus exporter port
-PROMETHEUS_EXPORTER_PORT=8889
+# -----------------------------------------------------------------------------
+# TELEMETRYFLOW SDK - Batch Settings
+# -----------------------------------------------------------------------------
+# Batch timeout in milliseconds (default: 5000)
+TELEMETRYFLOW_BATCH_TIMEOUT=5000
 
-# Health check port
-HEALTH_PORT=13133
+# Max batch size (default: 512)
+TELEMETRYFLOW_BATCH_MAX_SIZE=512
+
+# -----------------------------------------------------------------------------
+# TELEMETRYFLOW SDK - Signals
+# -----------------------------------------------------------------------------
+# Enable specific signals (all enabled by default)
+TELEMETRYFLOW_ENABLE_TRACES=true
+TELEMETRYFLOW_ENABLE_METRICS=true
+TELEMETRYFLOW_ENABLE_LOGS=true
+
+# Enable exemplars for metrics-to-traces correlation (default: true)
+TELEMETRYFLOW_ENABLE_EXEMPLARS=true
+
+# -----------------------------------------------------------------------------
+# TELEMETRYFLOW SDK - Rate Limiting
+# -----------------------------------------------------------------------------
+# Maximum requests per second (0 = unlimited)
+TELEMETRYFLOW_RATE_LIMIT=0
 
 # -----------------------------------------------------------------------------
-# Logging Configuration
+# LOGGING
 # -----------------------------------------------------------------------------
 LOG_LEVEL=info
 LOG_FORMAT=json
@@ -104,7 +157,7 @@ APP_PORT=8080
 APP_DEBUG=false
 
 # -----------------------------------------------------------------------------
-# Database Configuration (for RESTful API generator)
+# DATABASE (for RESTful API generator)
 # -----------------------------------------------------------------------------
 DB_DRIVER=postgresql
 DB_HOST=localhost
@@ -114,7 +167,7 @@ DB_USER=postgres
 DB_PASSWORD=
 
 # -----------------------------------------------------------------------------
-# Security Configuration (for RESTful API generator)
+# SECURITY (for RESTful API generator)
 # -----------------------------------------------------------------------------
 SECRET_KEY=change-me-in-production
 JWT_SECRET_KEY=change-me-in-production

CHANGELOG.md

@@ -7,7 +7,7 @@
 
   <h3>TelemetryFlow Python SDK</h3>
 
-[![Version](https://img.shields.io/badge/Version-1.1.1-orange.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.1.2-orange.svg)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org)
 [![OTEL SDK](https://img.shields.io/badge/OpenTelemetry_SDK-1.28.0-blueviolet)](https://opentelemetry.io/)
@@ -30,10 +30,95 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.2] - 2025-01-04
+
+### Added
+
+- **TFO v2 API Configuration Alignment**: Updated SDK configuration to align with TFO-Collector v1.1.2 (OCB-native)
+  - 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
+
+- Updated version to 1.1.2 to align with TFO-Collector v1.1.2 release
+- Default endpoint changed from `api.telemetryflow.id:4317` to `localhost:4317` for development
+- Added `TELEMETRYFLOW_PROTOCOL` and `TELEMETRYFLOW_TIMEOUT` environment variables
+
+### SDK Configuration Structure
+
+```yaml
+# 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.1.2"
+    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

CONTRIBUTING.md

@@ -7,7 +7,7 @@
 
   <h3>TelemetryFlow Python SDK</h3>
 
-[![Version](https://img.shields.io/badge/Version-1.1.1-orange.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.1.2-orange.svg)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org)
 [![OTEL SDK](https://img.shields.io/badge/OpenTelemetry_SDK-1.28.0-blueviolet)](https://opentelemetry.io/)

README.md

@@ -7,7 +7,7 @@
 
   <h3>TelemetryFlow Python SDK</h3>
 
-[![Version](https://img.shields.io/badge/Version-1.1.1-orange.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.1.2-orange.svg)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org)
 [![OTEL SDK](https://img.shields.io/badge/OpenTelemetry_SDK-1.28.0-blueviolet)](https://opentelemetry.io/)

SECURITY.md

@@ -7,7 +7,7 @@
 
   <h3>TelemetryFlow Python SDK</h3>
 
-[![Version](https://img.shields.io/badge/Version-1.1.1-orange.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.1.2-orange.svg)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org)
 [![OTEL SDK](https://img.shields.io/badge/OpenTelemetry_SDK-1.28.0-blueviolet)](https://opentelemetry.io/)