Merge branch 'main' into issue-688-fix

Author: ezhang6811

.coveragerc

@@ -1,11 +1,24 @@
 [run]
 ; This flag writes per-process coverage data files so subprocess coverage
-; can be combined with the main test process by pytest-cov. Works with COVERAGE_PROCESS_START in 
+; can be combined with the main test process by pytest-cov. Works with COVERAGE_PROCESS_START in
 ; tox.ini env variable
 ; see: https://coverage.readthedocs.io/en/6.5.0/cmd.html#combining-data-files-coverage-combine
 parallel = true
 
+[paths]
+; Normalize installed package paths back to source tree so coverage data
+; from different tox envs can be combined into a single report
+source =
+    aws-opentelemetry-distro/src/amazon
+    .tox/3.*/lib/python*/site-packages/amazon
+    */site-packages/amazon
+
 [report]
 include_namespace_packages = true
 fail_under = 95.00
-precision = 2
+precision = 2
+; Exclude test files that share the amazon namespace and pip build artifacts
+; from coverage measurement so only source code is reported
+omit =
+    */tests/*
+    */pip-build-env-*/*

.coveragerc-py314

@@ -0,0 +1,19 @@
+; Python 3.14 coverage config. See .coveragerc for details on shared settings.
+
+[run]
+parallel = true
+
+[paths]
+source =
+    aws-opentelemetry-distro/src/amazon
+    .tox/3.*/lib/python*/site-packages/amazon
+    */site-packages/amazon
+
+[report]
+include_namespace_packages = true
+fail_under = 95.00
+precision = 2
+omit =
+    */instrumentation/crewai/*
+    */tests/*
+    */pip-build-env-*/*

.coveragerc-py39

@@ -1,10 +1,30 @@
 [run]
-omit =
-    */instrumentation/crewai/*
-    */instrumentation/langchain/*
-    */instrumentation/mcp/*
+; This flag writes per-process coverage data files so subprocess coverage
+; can be combined with the main test process by pytest-cov. Works with COVERAGE_PROCESS_START in
+; tox.ini env variable
+; see: https://coverage.readthedocs.io/en/6.5.0/cmd.html#combining-data-files-coverage-combine
+parallel = true
+
+[paths]
+; Normalize installed package paths back to source tree so coverage data
+; from different tox envs can be combined into a single report
+source =
+    aws-opentelemetry-distro/src/amazon
+    .tox/3.*/lib/python*/site-packages/amazon
+    */site-packages/amazon
 
 [report]
 include_namespace_packages = true
 fail_under = 95.00
 precision = 2
+; Exclude framework instrumentation not installed on 3.9,
+; test files that share the amazon namespace, and pip build artifacts
+; so only source code is reported
+omit =
+    */instrumentation/crewai/*
+    */instrumentation/llama_index/*
+    */instrumentation/langchain/*
+    */instrumentation/mcp/*
+    */instrumentation/openai_agents/*
+    */tests/*
+    */pip-build-env-*/*

.github/actions/set_up/action.yml

@@ -43,6 +43,24 @@ runs:
       if: ${{ inputs.run_unit_tests == 'true' }}
       shell: bash
       run: |
-        ENV_NAME="${{ inputs.python_version }}-test-${{ inputs.package_name }}"
-        echo "Running tox env: $ENV_NAME"
-        tox -e "$ENV_NAME" -- -ra
+        PY_VERSION="${{ inputs.python_version }}"
+        # we intend for new or unrecognized Python versions to fail if a new Python version is added to the test 
+        # to ensure they are not silently skipped from testing
+        ENVS=$(tox list -q | grep "^${PY_VERSION}-test-" | sed 's/ .*//' | tr '\n' ',' | sed 's/,$//' || true)
+        echo "Running tox envs: $ENVS"
+        tox --parallel auto --parallel-live -e "$ENVS" -- -v
+
+    - name: Combine and check coverage
+      if: ${{ inputs.run_unit_tests == 'true' }}
+      shell: bash
+      run: |
+        pip install coverage
+        if [ "${{ inputs.python_version }}" = "3.9" ]; then
+          RCFILE=.coveragerc-py39
+        elif [ "${{ inputs.python_version }}" = "3.14" ]; then
+          RCFILE=.coveragerc-py314
+        else
+          RCFILE=.coveragerc
+        fi
+        coverage combine --rcfile=$RCFILE
+        coverage report --rcfile=$RCFILE

CHANGELOG.md

@@ -12,12 +12,22 @@ If your change does not need a CHANGELOG entry, add the "skip changelog" label t
 
 ## Unreleased
 
+- fix(langchain-instrumentor): expand provider detection for all supported LLM providers
+  ([#702](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/702))
+- feat: add LLO handler support for gen_ai.input.messages, gen_ai.output.messages, and gen_ai.system_instructions
+  ([#699](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/699))
+- feat: suppress redundant HTTP/ASGI and initialization spans in MCP instrumentation
+  ([#695](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/695))
+- feat: [BREAKING CHANGE] introduce AWS_AGENTIC_OBSERVABILITY_OPT_IN and refactor agent observability config
+  ([#691](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/691))
 - feat: propagate HTTP context for MCP requests and prefix all span names with mcp
   ([#683](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/683))
 - feat: add threading instrumentation dependency
   ([#685](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/685))
 - feat: add openai-agents-v2 instrumentation dependency
   ([#684](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/684))
+- feat: add BaggageSpanProcessor by default in ADOT
+  ([#687](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/687))
 - feat: Rewrite CrewAI instrumentation using Event based approach
   ([#681](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/681))
 
@@ -37,6 +47,8 @@ If your change does not need a CHANGELOG entry, add the "skip changelog" label t
   ([#658](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/658))
 - Fix AwsCloudWatchOtlpBatchLogRecordProcessor custom _export not being invoked; rename otlp_aws_logs_exporter to otlp_aws_log_record_exporter
   ([#611](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/611))
+- Add native LlamaIndex instrumentation support
+  ([#595](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/595))
 - Add native CrewAI instrumentation support
   ([#586](https://github.com/aws-observability/aws-otel-python-instrumentation/pull/586))
 

aws-opentelemetry-distro/pyproject.toml

@@ -105,9 +105,14 @@ aws_configurator = "amazon.opentelemetry.distro.aws_opentelemetry_configurator:A
 aws_distro = "amazon.opentelemetry.distro.aws_opentelemetry_distro:AwsOpenTelemetryDistro"
 
 [project.entry-points.opentelemetry_instrumentor]
+aws_llama-index = "amazon.opentelemetry.distro.instrumentation.llama_index:LlamaIndexInstrumentor"
 aws_crewai = "amazon.opentelemetry.distro.instrumentation.crewai:CrewAIInstrumentor"
 aws_langchain = "amazon.opentelemetry.distro.instrumentation.langchain:LangChainInstrumentor"
 aws_mcp = "amazon.opentelemetry.distro.instrumentation.mcp:McpInstrumentor"
+# Wraps the upstream OTel OpenAI Agents instrumentor under a unique entry point name.
+# This allows us to disable 3rd party "openai_agents" entry points in the opt-in path
+# while keeping OpenAI Agents instrumentation active via this alias.
+aws_openai_agents = "opentelemetry.instrumentation.openai_agents:OpenAIAgentsInstrumentor"
 
 [project.urls]
 Homepage = "https://github.com/aws-observability/aws-otel-python-instrumentation/tree/main/aws-opentelemetry-distro"

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/_utils.py

@@ -10,7 +10,9 @@
 
 _logger: Logger = getLogger(__name__)
 
+# Maintained for backwards compatibility. New users should use AWS_AGENTIC_OBSERVABILITY_OPT_IN instead.
 AGENT_OBSERVABILITY_ENABLED = "AGENT_OBSERVABILITY_ENABLED"
+AWS_AGENTIC_OBSERVABILITY_OPT_IN = "AWS_AGENTIC_OBSERVABILITY_OPT_IN"
 OTEL_METRICS_ADD_APPLICATION_SIGNALS_DIMENSIONS = "OTEL_METRICS_ADD_APPLICATION_SIGNALS_DIMENSIONS"
 
 
@@ -35,10 +37,20 @@ def is_installed(req: str) -> bool:
 
 
 def is_agent_observability_enabled() -> bool:
-    """Is the Agentic AI monitoring flag set to true?"""
+    # Maintained for backwards compatibility. New users should use AWS_AGENTIC_OBSERVABILITY_OPT_IN instead.
     return os.environ.get(AGENT_OBSERVABILITY_ENABLED, "false").lower() == "true"
 
 
+def is_aws_agentic_observability_opt_in() -> bool:
+    """Is the AI observability opt-in flag set to true?"""
+    return os.environ.get(AWS_AGENTIC_OBSERVABILITY_OPT_IN, "false").lower() == "true"
+
+
+def is_agentic_observability_enabled() -> bool:
+    """Returns True if either AGENT_OBSERVABILITY_ENABLED or AWS_AGENTIC_OBSERVABILITY_OPT_IN is set to true."""
+    return is_agent_observability_enabled() or is_aws_agentic_observability_opt_in()
+
+
 def should_add_application_signals_dimensions() -> bool:
     """Should Service and Environment Application Signals dimensions be added to EMF logs?"""
     return os.environ.get(OTEL_METRICS_ADD_APPLICATION_SIGNALS_DIMENSIONS, "true").lower() == "true"

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/aws_opentelemetry_configurator.py

@@ -17,7 +17,7 @@
 
 from amazon.opentelemetry.distro._aws_attribute_keys import AWS_LOCAL_SERVICE, AWS_SERVICE_TYPE
 from amazon.opentelemetry.distro._aws_resource_attribute_configurator import get_service_attribute
-from amazon.opentelemetry.distro._utils import get_aws_session, is_agent_observability_enabled
+from amazon.opentelemetry.distro._utils import get_aws_session, is_agentic_observability_enabled
 from amazon.opentelemetry.distro.always_record_sampler import AlwaysRecordSampler
 from amazon.opentelemetry.distro.attribute_propagating_span_processor_builder import (
     AttributePropagatingSpanProcessorBuilder,
@@ -204,7 +204,7 @@ def _initialize_components():
             AwsEksResourceDetector(),
             AwsEcsResourceDetector(),
         ]
-        if not (_is_lambda_environment() or is_agent_observability_enabled())
+        if not (_is_lambda_environment() or is_agentic_observability_enabled())
         else []
     )
 
@@ -326,7 +326,7 @@ def _export_unsampled_span_for_lambda(trace_provider: TracerProvider, resource:
 
 
 def _export_unsampled_span_for_agent_observability(trace_provider: TracerProvider, resource: Resource = None):
-    if not is_agent_observability_enabled():
+    if not is_agentic_observability_enabled():
         return
 
     traces_endpoint = os.environ.get(OTEL_EXPORTER_OTLP_TRACES_ENDPOINT)
@@ -467,7 +467,7 @@ def _customize_log_record_processor(logger_provider: LoggerProvider, log_exporte
     if not log_exporter:
         return
 
-    if is_agent_observability_enabled():
+    if is_agentic_observability_enabled():
         # pylint: disable=import-outside-toplevel
         from amazon.opentelemetry.distro.exporter.otlp.aws.logs._aws_cw_otlp_batch_log_record_processor import (
             AwsCloudWatchOtlpBatchLogRecordProcessor,
@@ -519,20 +519,18 @@ def _customize_span_processors(provider: TracerProvider, resource: Resource, sam
     if _is_lambda_environment():
         provider.add_span_processor(AwsLambdaSpanProcessor())
 
-    # We always send 100% spans to Genesis platform for agent observability because
+    # Propagates baggage entries matching OTEL_BAGGAGE_SPAN_ATTRIBUTE_KEYS into span attributes.
+    baggage_keys: set[str] = _parse_otel_baggage_keys_env_var()
+
+    # We always send 100% spans to AgentCore Runtime platform for agent observability because
     # AI applications typically have low throughput traffic patterns and require
     # comprehensive monitoring to catch subtle failure modes like hallucinations
     # and quality degradation that sampling could miss.
-    # Add session.id baggage attribute to span attributes to support AI Agent use cases
-    # enabling session ID tracking in spans.
-    if is_agent_observability_enabled():
+    if is_agentic_observability_enabled():
         _export_unsampled_span_for_agent_observability(provider, resource)
-        # propagates baggage entries matching OTEL_BAGGAGE_SPAN_ATTRIBUTE_KEYS into span attributes
-        raw: str = os.environ.get(OTEL_BAGGAGE_SPAN_ATTRIBUTE_KEYS, "").strip()
-        keys: set[str] = {k.strip() for k in raw.split(",") if k.strip()}
+        baggage_keys.add("session.id")
 
-        keys.add("session.id")
-        provider.add_span_processor(BaggageSpanProcessor(lambda key: key in keys))
+    provider.add_span_processor(BaggageSpanProcessor(lambda key: key in baggage_keys))
 
     if not _is_application_signals_enabled():
         return
@@ -635,7 +633,7 @@ def _customize_resource(resource: Resource) -> Resource:
 
     custom_attributes = {AWS_LOCAL_SERVICE: service_name}
 
-    if is_agent_observability_enabled():
+    if is_agentic_observability_enabled():
         # Add aws.service.type if it doesn't exist in the resource
         if resource and resource.attributes.get(AWS_SERVICE_TYPE) is None:
             # Set a default agent type for AI agent observability
@@ -737,6 +735,11 @@ def _fetch_logs_header() -> OtlpLogHeaderSetting:
     return _otlp_log_header_setting_cache
 
 
+def _parse_otel_baggage_keys_env_var() -> set[str]:
+    raw: str = os.environ.get(OTEL_BAGGAGE_SPAN_ATTRIBUTE_KEYS, "").strip()
+    return {k.strip() for k in raw.split(",") if k.strip()}
+
+
 def _clear_logs_header_cache():
     """Clear the singleton cache for OtlpLogHeaderSetting. Used primarily for testing."""
     global _otlp_log_header_setting_cache  # pylint: disable=global-statement
@@ -916,7 +919,7 @@ def _create_aws_otlp_exporter(endpoint: str, service: str, region: str):
         from amazon.opentelemetry.distro.exporter.otlp.aws.traces.otlp_aws_span_exporter import OTLPAwsSpanExporter
 
         if service == XRAY_SERVICE:
-            if is_agent_observability_enabled():
+            if is_agentic_observability_enabled():
                 # Span exporter needs an instance of logger provider in ai agent
                 # observability case because we need to split input/output prompts
                 # from span attributes and send them to the logs pipeline per