Enhance TFO-Python-SDK with OTEL Autoinstrumentation (Fixing CI-Builder)

Author: zeroc0d3

.github/workflows/ci.yml

@@ -105,7 +105,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.12', '3.13']
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

CHANGELOG.md

@@ -34,6 +34,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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.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`)
@@ -73,10 +77,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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.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
 
+### Fixed
+
+- **gRPC Header Case Sensitivity**: Fixed gRPC exporter to use lowercase header keys (gRPC metadata specification requires lowercase keys)
+
 ### SDK Configuration Structure
 
 ```yaml

CONTRIBUTING.md

@@ -53,7 +53,7 @@ By participating in this project, you agree to maintain a respectful and inclusi
 
 ### Prerequisites
 
-- Python 3.10 or higher
+- Python 3.12 or higher (minimum supported version)
 - Git
 - Make (optional, for using Makefile commands)
 

docs/BUILD-SYSTEM.md

@@ -60,7 +60,7 @@ graph TB
 
 ### Python Version
 
-Python 3.12 or higher is required:
+Python 3.12 or higher is required (tested on 3.12 and 3.13):
 
 ```bash
 python --version  # Should be 3.12+
@@ -80,17 +80,26 @@ Or with all optional dependencies:
 pip install -e ".[dev,http,grpc]"
 ```
 
+The `[dev]` extra includes all development tools:
+
+- pytest, pytest-asyncio, pytest-cov - Testing
+- mypy - Type checking
+- ruff - Linting
+- black, isort - Formatting
+- pre-commit - Git hooks
+- build - Package building (wheel/sdist)
+
 ### Required Tools
 
-| Tool | Purpose | Installation |
-|------|---------|--------------|
-| pip | Package installer | Built-in |
-| pytest | Testing | `pip install pytest` |
-| ruff | Linting/formatting | `pip install ruff` |
-| mypy | Type checking | `pip install mypy` |
-| black | Code formatting | `pip install black` |
-| build | Package building | `pip install build` |
-| twine | Package publishing | `pip install twine` |
+| Tool   | Purpose            | Installation        |
+| ------ | ------------------ | ------------------- |
+| pip    | Package installer  | Built-in            |
+| pytest | Testing            | Included in `[dev]` |
+| ruff   | Linting/formatting | Included in `[dev]` |
+| mypy   | Type checking      | Included in `[dev]` |
+| black  | Code formatting    | Included in `[dev]` |
+| build  | Package building   | Included in `[dev]` |
+| twine  | Package publishing | `pip install twine` |
 
 ## Project Structure
 
@@ -279,6 +288,7 @@ make format
 ```
 
 Equivalent to:
+
 ```bash
 black src/ tests/
 isort src/ tests/
@@ -321,8 +331,9 @@ make build
 ```
 
 Creates:
-- `dist/telemetryflow_sdk-1.1.1-py3-none-any.whl`
-- `dist/telemetryflow_sdk-1.1.1.tar.gz`
+
+- `dist/telemetryflow_sdk-1.1.2-py3-none-any.whl`
+- `dist/telemetryflow_sdk-1.1.2.tar.gz`
 
 #### make clean
 
@@ -333,6 +344,7 @@ make clean
 ```
 
 Removes:
+
 - `build/`
 - `dist/`
 - `*.egg-info/`
@@ -497,18 +509,18 @@ ls -la dist/
 
 ```
 dist/
-├── telemetryflow_sdk-1.1.1-py3-none-any.whl  # Wheel (binary)
-└── telemetryflow_sdk-1.1.1.tar.gz            # Source distribution
+├── telemetryflow_sdk-1.1.2-py3-none-any.whl  # Wheel (binary)
+└── telemetryflow_sdk-1.1.2.tar.gz            # Source distribution
 ```
 
 ### Installing Built Package
 
 ```bash
 # Install wheel
-pip install dist/telemetryflow_sdk-1.1.1-py3-none-any.whl
+pip install dist/telemetryflow_sdk-1.1.2-py3-none-any.whl
 
 # Install from source
-pip install dist/telemetryflow_sdk-1.1.1.tar.gz
+pip install dist/telemetryflow_sdk-1.1.2.tar.gz
 ```
 
 ## Publishing
@@ -669,7 +681,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "telemetryflow-sdk"
-version = "1.1.1"
+version = "1.1.2"
 requires-python = ">=3.12"
 
 [tool.pytest.ini_options]
@@ -697,7 +709,36 @@ line-length = 100
 
 ### GitHub Actions
 
-Create `.github/workflows/ci.yml`:
+The project uses GitHub Actions for CI/CD with the following workflows:
+
+| Workflow      | Trigger           | Purpose                                |
+| ------------- | ----------------- | -------------------------------------- |
+| `ci.yml`      | Push/PR           | Lint, test, build verification         |
+| `docker.yml`  | Push to main/tags | Build Docker images                    |
+| `release.yml` | Tags (v*.*.\*)    | Publish to PyPI, create GitHub release |
+
+### Python Version Matrix
+
+CI tests are run on **Python 3.12 and 3.13** to ensure compatibility:
+
+```yaml
+strategy:
+  matrix:
+    python-version: ["3.12", "3.13"]
+```
+
+### CI Jobs
+
+The CI workflow includes:
+
+1. **Lint & Code Quality** - Runs `make ci-lint` (ruff, mypy, format checks)
+2. **Unit Tests** - Runs `make ci-test-unit` on Python 3.12 and 3.13
+3. **Integration Tests** - Runs `make ci-test-integration`
+4. **Build Verification** - Tests on Ubuntu, macOS, and Windows
+5. **Security Scan** - Runs `make ci-security` (bandit)
+6. **Coverage Report** - Generates and uploads coverage reports
+
+### Example CI Configuration
 
 ```yaml
 name: CI
@@ -724,16 +765,13 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: pip install -e ".[dev]"
+        run: make ci-deps
 
       - name: Lint
-        run: make lint
-
-      - name: Type check
-        run: make typecheck
+        run: make ci-lint
 
       - name: Test
-        run: make test-coverage
+        run: make ci-test-unit
 
   build:
     runs-on: ubuntu-latest
@@ -747,10 +785,11 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Install dependencies
+        run: make ci-deps
+
       - name: Build
-        run: |
-          pip install build
-          make build
+        run: make ci-build
 
       - name: Upload artifacts
         uses: actions/upload-artifact@v4

docs/TESTING.md

@@ -449,15 +449,22 @@ pie title Coverage Targets by Layer
     "Client (85%+)" : 85
 ```
 
-| Layer | Target | Focus Areas |
-|-------|--------|-------------|
-| Domain | 90%+ | Value objects, validation |
-| Application | 85%+ | Commands, queries, buses |
-| Infrastructure | 80%+ | Handlers, exporters |
-| Client | 85%+ | Public API, lifecycle |
+| Layer          | Target | Focus Areas               |
+| -------------- | ------ | ------------------------- |
+| Domain         | 90%+   | Value objects, validation |
+| Application    | 85%+   | Commands, queries, buses  |
+| Infrastructure | 80%+   | Handlers, exporters       |
+| Client         | 85%+   | Public API, lifecycle     |
 
 ## CI/CD Integration
 
+### Supported Python Versions
+
+The SDK is tested on **Python 3.12 and 3.13**:
+
+- **Python 3.12**: Minimum supported version (LTS)
+- **Python 3.13**: Latest stable version
+
 ### GitHub Actions Example
 
 ```yaml
@@ -484,27 +491,19 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+      - name: Install CI dependencies
+        run: make ci-deps
 
       - name: Run linting
-        run: |
-          ruff check src/ tests/
+        run: make ci-lint
 
-      - name: Run type checking
-        run: |
-          mypy src/
-
-      - name: Run tests with coverage
-        run: |
-          pytest --cov=telemetryflow --cov-report=xml
+      - name: Run unit tests
+        run: make ci-test-unit
 
       - name: Upload coverage
         uses: codecov/codecov-action@v4
         with:
-          file: ./coverage.xml
+          file: ./coverage-unit.xml
 ```
 
 ### Pre-commit Hooks
@@ -618,6 +617,7 @@ def test_record_histogram_with_attributes(self, client):
 ### Tests Hanging
 
 If tests hang, check for:
+
 - Unended spans
 - Unclosed connections
 - Missing shutdown calls