Merge branch 'main' into fix/gh-609

Author: ishymko

.github/actions/spelling/allow.txt

@@ -63,6 +63,7 @@ Llm
 lstrips
 mikeas
 mockurl
+mysqladmin
 notif
 oauthoidc
 oidc
@@ -71,6 +72,7 @@ otherurl
 postgres
 POSTGRES
 postgresql
+proot
 protoc
 pyi
 pypistats

.github/actions/spelling/patterns.txt

@@ -0,0 +1,2 @@
+# Ignore URLs
+https?://\S+

.github/workflows/linter.yaml

@@ -27,15 +27,13 @@ jobs:
 
       - name: Run Ruff Linter
         id: ruff-lint
-        uses: astral-sh/ruff-action@v3
+        run: uv run ruff check --output-format=github
         continue-on-error: true
 
       - name: Run Ruff Formatter
         id: ruff-format
-        uses: astral-sh/ruff-action@v3
+        run: uv run ruff format --check
         continue-on-error: true
-        with:
-          args: "format --check"
 
       - name: Run MyPy Type Checker
         id: mypy

pyproject.toml

@@ -72,9 +72,10 @@ exclude = ["tests/"]
 testpaths = ["tests"]
 python_files = "test_*.py"
 python_functions = "test_*"
-addopts = "-ra --strict-markers"
+addopts = "-ra --strict-markers --dist loadgroup"
 markers = [
   "asyncio: mark a test as a coroutine that should be run by pytest-asyncio",
+  "xdist_group: mark a test to run in a specific sequential group for isolation",
 ]
 
 [tool.pytest-asyncio]
@@ -93,6 +94,7 @@ dev = [
   "pytest-asyncio>=0.26.0",
   "pytest-cov>=6.1.1",
   "pytest-mock>=3.14.0",
+  "pytest-xdist>=3.6.1",
   "respx>=0.20.2",
   "ruff>=0.12.8",
   "uv-dynamic-versioning>=0.8.2",

scripts/docker-compose.test.yml

@@ -0,0 +1,29 @@
+services:
+  postgres:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_USER: a2a
+      POSTGRES_PASSWORD: a2a_password
+      POSTGRES_DB: a2a_test
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  mysql:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: a2a_test
+      MYSQL_USER: a2a
+      MYSQL_PASSWORD: a2a_password
+    ports:
+      - "3306:3306"
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h localhost -u root -proot"]
+      interval: 10s
+      timeout: 5s
+      retries: 5

scripts/run_integration_tests.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+set -e
+
+# Get the directory of this script
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Docker compose file path
+COMPOSE_FILE="$SCRIPT_DIR/docker-compose.test.yml"
+
+# Initialize variables
+DEBUG_MODE=false
+STOP_MODE=false
+SERVICES=()
+PYTEST_ARGS=()
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --debug)
+      DEBUG_MODE=true
+      shift
+      ;;
+    --stop)
+      STOP_MODE=true
+      shift
+      ;;
+    --postgres)
+      SERVICES+=("postgres")
+      shift
+      ;;
+    --mysql)
+      SERVICES+=("mysql")
+      shift
+      ;;
+    *)
+      # Preserve other arguments for pytest
+      PYTEST_ARGS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+# Handle --stop
+if [[ "$STOP_MODE" == "true" ]]; then
+  echo "Stopping test databases..."
+  docker compose -f "$COMPOSE_FILE" down
+  exit 0
+fi
+
+# Default to running both databases if none specified
+if [[ ${#SERVICES[@]} -eq 0 ]]; then
+  SERVICES=("postgres" "mysql")
+fi
+
+# Cleanup function to stop docker containers
+cleanup() {
+    echo "Stopping test databases..."
+    docker compose -f "$COMPOSE_FILE" down
+}
+
+# Start the databases
+echo "Starting/Verifying databases: ${SERVICES[*]}..."
+docker compose -f "$COMPOSE_FILE" up -d --wait "${SERVICES[@]}"
+
+# Set up environment variables based on active services
+# Only export DSNs for started services so tests skip missing ones
+for service in "${SERVICES[@]}"; do
+  if [[ "$service" == "postgres" ]]; then
+    export POSTGRES_TEST_DSN="postgresql+asyncpg://a2a:a2a_password@localhost:5432/a2a_test"
+  elif [[ "$service" == "mysql" ]]; then
+    export MYSQL_TEST_DSN="mysql+aiomysql://a2a:a2a_password@localhost:3306/a2a_test"
+  fi
+done
+
+# Handle --debug mode
+if [[ "$DEBUG_MODE" == "true" ]]; then
+  echo "---------------------------------------------------"
+  echo "Debug mode enabled. Databases are running."
+  echo "You can connect to them using the following DSNs."
+  echo ""
+  echo "Run the following commands to set up your environment:"
+  echo ""
+  [[ -n "$POSTGRES_TEST_DSN" ]] && echo "export POSTGRES_TEST_DSN=\"$POSTGRES_TEST_DSN\""
+  [[ -n "$MYSQL_TEST_DSN" ]] && echo "export MYSQL_TEST_DSN=\"$MYSQL_TEST_DSN\""
+  echo ""
+  echo "---------------------------------------------------"
+  echo "Run ./scripts/run_integration_tests.sh --stop to shut databases down."
+  exit 0
+fi
+
+# Register cleanup trap for normal test run
+trap cleanup EXIT
+
+# Run the tests
+echo "Running integration tests..."
+cd "$PROJECT_ROOT"
+
+uv run --extra all pytest -v \
+    tests/server/tasks/test_database_task_store.py \
+    tests/server/tasks/test_database_push_notification_config_store.py \
+    "${PYTEST_ARGS[@]}"

src/a2a/utils/telemetry.py

@@ -18,6 +18,16 @@
 - Automatic recording of exceptions and setting of span status.
 - Selective method tracing in classes using include/exclude lists.
 
+Configuration:
+- Environment Variable Control: OpenTelemetry instrumentation can be
+  disabled using the `OTEL_INSTRUMENTATION_A2A_SDK_ENABLED` environment
+  variable.
+
+  - Default: `true` (tracing enabled when OpenTelemetry is installed)
+  - To disable: Set `OTEL_INSTRUMENTATION_A2A_SDK_ENABLED=false`
+  - Case insensitive: 'true', 'True', 'TRUE' all enable tracing
+  - Any other value disables tracing and logs a debug message
+
 Usage:
     For a single function:
     ```python
@@ -57,10 +67,13 @@ def internal_method(self):
 import functools
 import inspect
 import logging
+import os
 
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
+from typing_extensions import Self
+
 
 if TYPE_CHECKING:
     from opentelemetry.trace import SpanKind as SpanKindType
@@ -74,19 +87,41 @@ def internal_method(self):
     from opentelemetry.trace import SpanKind as _SpanKind
     from opentelemetry.trace import StatusCode
 
+    otel_installed = True
+
 except ImportError:
     logger.debug(
         'OpenTelemetry not found. Tracing will be disabled. '
         'Install with: \'pip install "a2a-sdk[telemetry]"\''
     )
+    otel_installed = False
+
+ENABLED_ENV_VAR = 'OTEL_INSTRUMENTATION_A2A_SDK_ENABLED'
+INSTRUMENTING_MODULE_NAME = 'a2a-python-sdk'
+INSTRUMENTING_MODULE_VERSION = '1.0.0'
+
+# Check if tracing is enabled via environment variable
+env_value = os.getenv(ENABLED_ENV_VAR, 'true')
+otel_enabled = env_value.lower() == 'true'
+
+# Log when tracing is explicitly disabled via environment variable
+if otel_installed and not otel_enabled:
+    logger.debug(
+        'A2A OTEL instrumentation disabled via environment variable '
+        '%s=%r. Tracing will be disabled.',
+        ENABLED_ENV_VAR,
+        env_value,
+    )
+
+if not otel_installed or not otel_enabled:
 
     class _NoOp:
         """A no-op object that absorbs all tracing calls when OpenTelemetry is not installed."""
 
         def __call__(self, *args: Any, **kwargs: Any) -> Any:
             return self
 
-        def __enter__(self) -> '_NoOp':
+        def __enter__(self) -> Self:
             return self
 
         def __exit__(self, *args: object, **kwargs: Any) -> None:
@@ -99,12 +134,9 @@ def __getattr__(self, name: str) -> Any:
     _SpanKind = _NoOp()  # type: ignore
     StatusCode = _NoOp()  # type: ignore
 
-SpanKind = _SpanKind
+SpanKind = _SpanKind  # type: ignore
 __all__ = ['SpanKind']
 
-INSTRUMENTING_MODULE_NAME = 'a2a-python-sdk'
-INSTRUMENTING_MODULE_VERSION = '1.0.0'
-
 
 def trace_function(  # noqa: PLR0915
     func: Callable | None = None,

tests/utils/test_telemetry.py

@@ -1,6 +1,8 @@
 import asyncio
+import importlib
+import sys
 
-from collections.abc import Generator
+from collections.abc import Callable, Generator
 from typing import Any, NoReturn
 from unittest import mock
 
@@ -30,6 +32,32 @@ def patch_trace_get_tracer(
         yield
 
 
+@pytest.fixture
+def reload_telemetry_module(
+    monkeypatch: pytest.MonkeyPatch,
+) -> Generator[Callable[[str | None], Any], None, None]:
+    """Fixture to handle telemetry module reloading with env var control."""
+
+    def _reload(env_value: str | None = None) -> Any:
+        if env_value is None:
+            monkeypatch.delenv(
+                'OTEL_INSTRUMENTATION_A2A_SDK_ENABLED', raising=False
+            )
+        else:
+            monkeypatch.setenv(
+                'OTEL_INSTRUMENTATION_A2A_SDK_ENABLED', env_value
+            )
+
+        sys.modules.pop('a2a.utils.telemetry', None)
+        module = importlib.import_module('a2a.utils.telemetry')
+        return module
+
+    yield _reload
+
+    # Cleanup to ensure other tests aren't affected by a "poisoned" sys.modules
+    sys.modules.pop('a2a.utils.telemetry', None)
+
+
 def test_trace_function_sync_success(mock_span: mock.MagicMock) -> None:
     @trace_function
     def foo(x, y):
@@ -198,3 +226,43 @@ def foo(self) -> str:
     assert obj.foo() == 'foo'
     assert hasattr(obj.foo, '__wrapped__')
     assert hasattr(obj, 'x')
+
+
+@pytest.mark.xdist_group(name='telemetry_isolation')
+@pytest.mark.parametrize(
+    'env_value,expected_tracing',
+    [
+        (None, True),  # Default: env var not set, tracing enabled
+        ('true', True),  # Explicitly enabled
+        ('True', True),  # Case insensitive
+        ('false', False),  # Disabled
+        ('', False),  # Empty string = false
+    ],
+)
+def test_env_var_controls_instrumentation(
+    reload_telemetry_module: Callable[[str | None], Any],
+    env_value: str | None,
+    expected_tracing: bool,
+) -> None:
+    """Test OTEL_INSTRUMENTATION_A2A_SDK_ENABLED controls span creation."""
+    telemetry_module = reload_telemetry_module(env_value)
+
+    is_noop = type(telemetry_module.trace).__name__ == '_NoOp'
+
+    assert is_noop != expected_tracing
+
+
+@pytest.mark.xdist_group(name='telemetry_isolation')
+def test_env_var_disabled_logs_message(
+    reload_telemetry_module: Callable[[str | None], Any],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Test that disabling via env var logs appropriate debug message."""
+    with caplog.at_level('DEBUG', logger='a2a.utils.telemetry'):
+        reload_telemetry_module('false')
+
+    assert (
+        'A2A OTEL instrumentation disabled via environment variable'
+        in caplog.text
+    )
+    assert 'OTEL_INSTRUMENTATION_A2A_SDK_ENABLED' in caplog.text