Add some docs and hook it into the system

Still not building content

Author: xrmx

docs/conf.py

@@ -28,21 +28,21 @@
 
 exp = "../exporter"
 exp_dirs = [
-    os.path.abspath("/".join(["../exporter", f, "src"]))
+    os.path.abspath("/".join([exp, f, "src"]))
     for f in listdir(exp)
     if isdir(join(exp, f))
 ]
 
 instr = "../instrumentation"
 instr_dirs = [
-    os.path.abspath("/".join(["../instrumentation", f, "src"]))
+    os.path.abspath("/".join([instr, f, "src"]))
     for f in listdir(instr)
-    if isdir(join(instr, f))
+    if isdir(join(instr, f)) and f != "opentelemetry-instrumentation-boto"
 ]
 
 instr_genai = "../instrumentation-genai"
 instr_genai_dirs = [
-    os.path.abspath("/".join(["../instrumentation-genai", f, "src"]))
+    os.path.abspath("/".join([instr_genai, f, "src"]))
     for f in listdir(instr_genai)
     if isdir(join(instr_genai, f))
 ]
@@ -56,24 +56,32 @@
 
 sdk_ext = "../sdk-extension"
 sdk_ext_dirs = [
-    os.path.abspath("/".join(["../sdk-extension", f, "src"]))
+    os.path.abspath("/".join([sdk_ext, f, "src"]))
     for f in listdir(sdk_ext)
     if isdir(join(sdk_ext, f))
 ]
 
 resource = "../resource"
 resource_dirs = [
-    os.path.abspath("/".join(["../resource", f, "src"]))
+    os.path.abspath("/".join([resource, f, "src"]))
     for f in listdir(resource)
     if isdir(join(resource, f))
 ]
+
+opamp = "../opamp"
+opamp_dirs = [
+    os.path.abspath("/".join([opamp, f, "src"]))
+    for f in listdir(opamp)
+    if isdir(join(opamp, f))
+]
 sys.path[:0] = (
     exp_dirs
     + instr_dirs
     + instr_genai_dirs
     + sdk_ext_dirs
     + prop_dirs
     + resource_dirs
+    + opamp_dirs
 )
 
 # -- Project information -----------------------------------------------------
@@ -115,7 +123,7 @@
         "https://opentracing-python.readthedocs.io/en/latest/",
         None,
     ),
-    "aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None),
+    "aiohttp": ("https://docs.aiohttp.org/en/stable/", None),
     "wrapt": ("https://wrapt.readthedocs.io/en/latest/", None),
     "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
     "opentelemetry": (

docs/index.rst

@@ -103,6 +103,14 @@ install <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>
 
     resource/**
 
+.. toctree::
+    :maxdepth: 2
+    :caption: OpAMP
+    :name: OpAMP
+    :glob:
+
+    opamp/**
+
 Indices and tables
 ------------------
 

docs/opamp/client.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Python - OpAMP Client
+===================================
+
+.. automodule:: opentelemetry._opamp
+    :members: agent, client
+    :undoc-members:
+    :show-inheritance:

opamp/opentelemetry-opamp-client/MANIFEST.rst

@@ -0,0 +1,9 @@
+graft src
+graft tests
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude __pycache__/*
+include CHANGELOG.md
+include MANIFEST.in
+include README.rst
+include LICENSE

opamp/opentelemetry-opamp-client/README.rst

@@ -14,6 +14,8 @@ Installation
     pip install opentelemetry-opamp-client
 
 
+This package provides an HTTP OpAMP client than can be used by OpenTelemetry distributions to provide remote config.
+
 References
 ----------
 * `OpenTelemetry OpAMP Client <https://opentelemetry-python-contrib.readthedocs.io/en/latest/opamp/client/client.html>`_

opamp/opentelemetry-opamp-client/src/opentelemetry/_opamp/agent.py

@@ -27,6 +27,78 @@
 logger = logging.getLogger(__name__)
 
 
+"""
+OpenTelemetry Python - OpAMP client
+-----------------------------------
+
+This package provides a bunch of classes that can be used by OpenTelemetry distributions implementors
+to implement remote config support via the OpAMP protocol.
+
+The client implements the following capabilities:
+- ReportsStatus
+- ReportsHeartbeat
+- AcceptsRemoteConfig
+- ReportsRemoteConfig
+
+These capabilities are enough to get a remote config from an opamp server, parse it, apply it and ack it.
+
+Since OpAMP APIs, config options or environment variables are not standardizes the distros are required
+to provide code doing so.
+OTel Python distros would need to provide their own message handler callback that implements the actual
+change of whatever configuration their backends sends.
+
+Please note that the API is not finalized yet and so the name is called ``_opamp`` with the underscore.
+
+Usage
+-----
+
+.. code-block:: python
+
+    import os
+
+    from opentelemetry._opamp import messages
+    from opentelemetry._opamp.agent import OpAMPAgent
+    from opentelemetry._opamp.client import OpAMPClient
+    from opentelemetry._opamp.proto import opamp_pb2 as opamp_pb2
+    from opentelemetry.sdk._configuration import _OTelSDKConfigurator
+    from opentelemetry.sdk.resources import OTELResourceDetector
+
+
+    def opamp_handler(agent: OpAMPAgent, client: OpAMPClient, message: opamp_pb2.ServerToAgent):
+        for config_filename, config in messages._decode_remote_config(message.remote_config):
+            print("do something")
+
+
+    class MyOpenTelemetryConfigurator(_OTelSDKConfigurator):
+        def _configure(self, **kwargs):
+            super()._configure(**kwargs)
+
+            enable_opamp = False
+            endpoint = os.environ.get("OTEL_PYTHON_OPAMP_ENDPOINT")
+            if endpoint:
+                # this is not great but we don't have the calculated resource attributes around
+                # see https://github.com/open-telemetry/opentelemetry-python/pull/4646 for creating
+                # an entry point distros can implement
+                resource = OTELResourceDetector().detect()
+                agent_identifying_attributes = {
+                    "service.name": resource.attributes.get("service.name"),
+                }
+                opamp_client = OpAMPClient(
+                    endpoint=endpoint,
+                    agent_identifying_attributes=agent_identifying_attributes,
+                )
+                opamp_agent = OpAMPAgent(
+                    interval=30,
+                    message_handler=opamp_handler,
+                    client=opamp_client,
+                )
+                opamp_agent.start()
+
+API
+---
+"""
+
+
 class _Job:
     """
     Represents a single request job, with retry/backoff metadata.

opamp/opentelemetry-opamp-client/src/opentelemetry/_opamp/client.py

@@ -43,6 +43,10 @@
 
 
 class OpAMPClient:
+    """
+    OpAMPClient implement the helpers for building and sending messages that the agent will use.
+    """
+
     def __init__(
         self,
         *,