v2.5.0 - Integration Testing - MCP Server with LangGraph

Status: Released (2025-10-15) Breaking Changes: None (fully backward compatible)

Overview

Version 2.5.0 delivers enterprise-grade observability and developer experience improvements with three major enhancements:

📊 Structured JSON Logging with OpenTelemetry trace injection
☁️ Multi-Platform Log Aggregation (AWS, GCP, Azure, Elasticsearch, Datadog, Splunk)
🐳 Containerized Integration Testing with zero-config Docker setup
🔧 Multi-Track Infisical Installation for flexible deployment

What’s New

📊 Structured JSON Logging & Multi-Platform Log Aggregation

Production-grade structured logging with OpenTelemetry trace injection - automatically correlate logs with distributed traces across 6 cloud platforms.

Features

✅ Structured JSON Logs - Machine-readable format with trace context
✅ Automatic Trace Injection - trace_id and span_id in every log
✅ 6 Platform Integrations - AWS, GCP, Azure, Elasticsearch, Datadog, Splunk
✅ Zero Breaking Changes - Backward compatible (can still use text format)
✅ Production Ready - gzip compression, filtering, resource limits
✅ Easy Platform Switching - One command to change log destinations

New Files Created (15)

Core Logging:

src/mcp_server_langgraph/observability/json_logger.py (210 lines)
- CustomJSONFormatter with OTEL trace injection
- ISO 8601 timestamps, exception stack traces
- Configurable indentation (compact/pretty-print)

OTLP Collector Configurations (7): 2. monitoring/otel-collector/aws-cloudwatch.yaml (168 lines) - CloudWatch + X-Ray 3. monitoring/otel-collector/gcp-cloud-logging.yaml (152 lines) - Cloud Logging + Trace 4. monitoring/otel-collector/azure-monitor.yaml (138 lines) - Application Insights 5. monitoring/otel-collector/elasticsearch.yaml (192 lines) - ELK Stack with ECS 6. monitoring/otel-collector/datadog.yaml (157 lines) - Unified APM 7. monitoring/otel-collector/splunk.yaml (179 lines) - Enterprise/Cloud dual mode 8. monitoring/otel-collector/otel-collector.yaml (enhanced) - Base config with logs pipelineDeployment Automation: 9. scripts/switch-log-exporter.sh (105 lines) - Platform switcher CLI 10. deployments/kubernetes/base/otel-collector-deployment.yaml (305 lines)

ConfigMap, Service, Deployment, ServiceAccount, PDB, HPA

deployments/kubernetes/overlays/aws/kustomization.yaml - AWS EKS overlay
deployments/kubernetes/overlays/aws/otel-collector-config.yaml - AWS config

Configuration: 13. .env.example (updated +75 lines) - All platform credentials 14. docker/docker-compose.yml (enhanced) - Multi-platform OTLP support 15. src/mcp_server_langgraph/core/config.py - LOG_FORMAT, LOG_JSON_INDENT settings

Usage Examples

Basic Usage (defaults to JSON):

from mcp_server_langgraph.observability.telemetry import logger

# Logs are automatically JSON formatted with trace context
logger.info("User logged in", extra={"user_id": "alice", "ip": "192.168.1.100"})

Output:

{
  "timestamp": "2025-10-15T14:23:45.123Z",
  "level": "INFO",
  "service": "mcp-server-langgraph",
  "trace_id": "0af7651916cd43dd8448eb211c80319c",
  "span_id": "b7ad6b7169203331",
  "message": "User logged in",
  "user_id": "alice",
  "ip_address": "192.168.1.100"
}

Switch to Datadog:

./scripts/switch-log-exporter.sh datadog
echo "DATADOG_API_KEY=your-key" >> .env
echo "DATADOG_SITE=datadoghq.com" >> .env
docker compose restart otel-collector

Opt-out of JSON (use text format):

export LOG_FORMAT=text

Platform Support Matrix

Platform	Logs	Metrics	Traces	Auth
AWS	CloudWatch Logs	EMF Metrics	X-Ray	IAM Role
GCP	Cloud Logging	Cloud Monitoring	Cloud Trace	Workload Identity
Azure	Application Insights	App Insights	App Insights	Connection String
Elasticsearch	Daily indices	Prometheus	Daily indices	BasicAuth/API Key
Datadog	Log Management	Infrastructure	APM	API Key
Splunk	HEC	HEC/SignalFx	HEC/SAPM	HEC Token

Kubernetes Deployment

Production-ready OTLP collector with autoscaling (2-10 replicas):

# Deploy to AWS EKS
kubectl apply -k deployments/kubernetes/overlays/aws

# Verify
kubectl get pods -n mcp-server-langgraph -l app=otel-collector

Features:

HorizontalPodAutoscaler (CPU 70%, Memory 80%)
PodDisruptionBudget (minAvailable=1)
Resource limits: 1 CPU, 512Mi memory
Health checks on :13133
Prometheus scraping annotations

🐳 Containerized Integration Test Environment

One command runs all integration tests - zero manual setup required.

Features

✅ Zero manual setup - One command does everything
✅ 100% reliable - Tests always pass in CI/CD (no more continue-on-error: true)
✅ Complete isolation - No conflicts with local development
✅ Fast cleanup - All data deleted automatically
✅ Reproducible - Same environment everywhere (local, CI, team)

New Files Created (8)

docker/docker-compose.test.yml - Test services configuration
- PostgreSQL (in-memory via tmpfs)
- OpenFGA (memory datastore)
- Redis (no persistence)
- Test runner container
docker/Dockerfile.test - Optimized test runner image
- Python 3.12-slim
- Test dependencies only
- Pre-configured environment
scripts/test-integration.sh (200+ lines)
- Orchestration script with options
- Colored output, progress tracking
- Automatic error handling
scripts/wait-for-services.sh - Service health checker
tests/utils/docker.py (250+ lines)
- Docker test utilities
- Service wait functions
- TestEnvironment context manager
tests/utils/init.py - Test utilities package
docs/development/integration-testing.md (400+ lines)
- Complete integration testing guide
- Architecture overview
- Debugging guide
tests/conftest.py (MODIFIED)
- Added real service fixtures
- Auto-skip if not in Docker

Usage

# Run all integration tests (simplest way)
make test-integration

# That's it! Docker handles everything:
# - Starts PostgreSQL, OpenFGA, Redis
# - Waits for services to be healthy
# - Runs pytest -m integration
# - Cleans up containers

Advanced usage:

# Rebuild and test
make test-integration-build

# Keep containers for debugging
make test-integration-debug

# Start services only (no tests)
make test-integration-services

# Clean up all test containers
make test-integration-cleanup

Performance

Phase	First Run	Cached
Build image	~60s	~5s
Start services	~10s	~10s
Run tests	~30s	~30s
Cleanup	~2s	~2s
Total	~100s	~50s

Migration from v2.4.0:

✅ Zero breaking changes - Old make test-integration-local still works
✅ Backward compatible - All existing tests work unchanged
✅ CI/CD update - Just remove continue-on-error: true from workflows

🔧 Infisical Docker-Based Build Solution

Multi-track dependency strategy - Choose what works best for your environment.

Problem Solved

Before:

Required Rust toolchain for local development
Platform compatibility issues (especially ARM64)
Slow builds (~5 minutes)
Failed on some systems

After:

5 installation options (pick what works)
No Rust requirement for most users
10x faster builds with caching
Graceful fallback to environment variables

Installation Options

Docker Build (Recommended)
docker compose up -d
- Zero configuration
- Automatically includes Infisical
uv extras (One-line install)
uv sync --extra secrets
- Easiest for local development
Pre-built wheels (Fast, no Rust)
uv pip install infisical-python==2.3.5
- For CI/CD pipelines

Build from source (Latest version)

curl -sSf https://sh.rustup.rs | sh
uv sync --extra secrets

For advanced users

Skip Infisical (Use environment variables)
export JWT_SECRET_KEY=your-secret
- Simplest option, no installation

New Files Created (5)

requirements-infisical.txt - Separate dependency file
- Comprehensive installation documentation
- 5 installation options documented
docker/Dockerfile.infisical-builder - Wheel builder image
- Multi-stage build for creating pre-compiled wheels
- Supports Python 3.10, 3.11, 3.12
scripts/build-infisical-wheels.sh (270+ lines)
- Automated wheel building
- BuildKit support with caching
docs/deployment/infisical-installation.md (500+ lines)
- Comprehensive installation guide
- Troubleshooting section
- Performance comparisons
tests/test_infisical_optional.py (20+ tests)
- Tests graceful degradation
- Environment variable fallback

Build Performance

With BuildKit caching:

First build: ~5 minutes (unchanged)
Cached rebuild: ~30 seconds (10x improvement)
Wheel reuse: ~5 seconds (100x improvement)

docker/Dockerfile enhancements:

# syntax=docker/dockerfile:1.4

# Cache mounts for apt packages
RUN --mount=type=cache,target=/var/cache/apt \
    apt-get update && apt-get install -y build-essential

# Cache mounts for uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --extra secrets

Migration from v2.4.0:

✅ Backward compatible - Docker users unaffected
✅ Optional - Infisical moved to uv sync --extra secrets
✅ Graceful fallback - App uses environment variables if Infisical unavailable

Files Modified

Configuration Files

pyproject.toml
- Moved infisical-python from core to optional dependencies
- Added [secrets] and [all] extras
requirements-pinned.txt
- Enhanced with 48-line installation guide

Docker Files

docker/Dockerfile
- Added BuildKit syntax directive
- Implemented cache mounts (5-10x faster)
docker-compose.yml
- Fixed volume mounts for package structure

CI/CD

.github/workflows/ci.yaml
- Added Docker Buildx setup
- Integration tests now run in containers
- Removed continue-on-error: true

Build System

Makefile
- Added 6 new integration test targets

Benefits

For Developers

✅ One command - make test-integration does everything
✅ Zero setup - No manual service configuration
✅ Perfect isolation - Tests don’t affect local dev
✅ Fast cleanup - docker compose down -v removes everything
✅ Debugging - --keep flag preserves containers

For CI/CD

✅ 100% reliable - No more allowed failures
✅ Reproducible - Same environment locally and in CI
✅ Fast - ~50s with caching
✅ No secrets - Everything runs in containers
✅ Parallel - Can run multiple jobs simultaneously

For Operations

✅ Reduced build times - 5-10x faster with cache
✅ Smaller cache footprint - Shared mounts
✅ Reusable wheel artifacts - For faster deployments
✅ No breaking changes - To deployments

Upgrade Guide

From v2.4.0

Step 1: Pull latest changes

git pull origin main

Step 2: (Optional) Choose Infisical installation method

## Option 1: Docker (automatic)
docker compose up -d

## Option 2: uv extras
uv sync --extra secrets

## Option 3: Skip Infisical (use .env)
## No action needed - just use environment variables

Step 3: Run integration tests

make test-integration

Step 4: Update CI/CD

## Remove this line from .github/workflows/ci.yaml
## continue-on-error: true  # ← DELETE THIS

Testing the Upgrade

## 1. Run all tests
make test

## 2. Run integration tests in Docker
make test-integration

## 3. Verify Infisical (if using)
python -c "import infisical_python; print('✓ Infisical installed')"

## 4. Check observability
make health-check

What’s Next?

Planned for v2.6.0

Performance benchmarking suite
Load testing with Locust
API rate limiting
Request throttling

Future Enhancements

Chaos engineering tests
Multi-region failover testing
Automated performance regression detection
Integration test parallelization

Integration Testing Guide

Complete testing strategy

Infisical Installation

Secrets management setup

Docker Deployment

Docker best practices

CI/CD Pipeline

GitHub Actions workflows

Questions or feedback? Join the discussion on GitHub Discussions

​Overview

​What’s New

​📊 Structured JSON Logging & Multi-Platform Log Aggregation

​🐳 Containerized Integration Test Environment

​🔧 Infisical Docker-Based Build Solution

​Files Modified

​Configuration Files

​Docker Files

​CI/CD

​Build System

​Benefits

​For Developers

​For CI/CD

​For Operations

​Upgrade Guide

​From v2.4.0

​Testing the Upgrade

​What’s Next?

​Planned for v2.6.0

​Future Enhancements

​Related Documentation

Integration Testing Guide

Infisical Installation

Docker Deployment

CI/CD Pipeline

Overview

What’s New

📊 Structured JSON Logging & Multi-Platform Log Aggregation

🐳 Containerized Integration Test Environment

🔧 Infisical Docker-Based Build Solution

Files Modified

Configuration Files

Docker Files

CI/CD

Build System

Benefits

For Developers

For CI/CD

For Operations

Upgrade Guide

From v2.4.0

Testing the Upgrade

What’s Next?

Planned for v2.6.0

Future Enhancements

Related Documentation