opentelemetry bridge

.ci/.jenkins_framework.yml

@@ -11,6 +11,7 @@ FRAMEWORK:
  - flask-1.1
  - flask-2.0
  - jinja2-3
+ - opentelemetry-newest
  - opentracing-newest
  - twisted-18
  - celery-4-flask-1.0

.ci/.jenkins_framework_full.yml

@@ -25,6 +25,7 @@ FRAMEWORK:
  - celery-5-flask-2
  - celery-5-django-3
  - celery-5-django-4
+ - opentelemetry-newest
  - opentracing-newest
  - opentracing-2.0
  - twisted-18

CHANGELOG.asciidoc

@@ -29,6 +29,17 @@ endif::[]
 //===== Bug fixes
 //
 
+=== Unreleased
+
+// Unreleased changes go here
+// When the next release happens, nest these changes under the "Python Agent version 6.x" heading
+[float]
+===== Features
+
+* Add OpenTelemetry API bridge {pull}1411[#1411]
+
+//[float]
+//===== Bug fixes
 
 
 [[release-notes-6.x]]

docs/index.asciidoc

@@ -25,7 +25,7 @@ include::./api.asciidoc[]
 
 include::./metrics.asciidoc[]
 
-include::./opentracing.asciidoc[]
+include::./opentelemetry.asciidoc[]
 
 include::./logging.asciidoc[]
 

docs/opentelemetry.asciidoc

@@ -0,0 +1,77 @@
+[[opentelemetry-bridge]]
+== OpenTelemetry API Bridge
+
+The Elastic APM OpenTelemetry bridge allows you to create Elastic APM `Transactions` and `Spans`,
+using the OpenTelemetry API. This allows users to utilize the Elastic APM agent's
+automatic instrumentations, while keeping custom instrumentations vendor neutral.
+
+If a span is created while there is no transaction active, it will result in an
+Elastic APM {apm-guide-ref}/transactions.html[`Transaction`]. Inner spans
+are mapped to Elastic APM {apm-guide-ref}/transaction-spans.html[`Span`].
+
+[float]
+[[opentelemetry-getting-started]]
+=== Getting started
+The first step in getting started with the OpenTelemetry bridge is to install the `opentelemetry` libraries:
+
+[source,bash]
+----
+pip install elastic-apm[opentelemetry]
+----
+
+Or if you already have installed `elastic-apm`:
+
+
+[source,bash]
+----
+pip install opentelemetry-api opentelemetry-sdk
+----
+
+
+[float]
+[[opentelemetry-usage]]
+=== Usage
+
+[source,python]
+----
+from elasticapm.contrib.opentelemetry import Tracer
+
+tracer = Tracer(__name__);
+with tracer.start_as_current_span("test"):
+ # Do some work
+----
+
+or
+
+[source,python]
+----
+from elasticapm.contrib.opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+with tracer.start_as_current_span("test"):
+ # Do some work
+----
+
+
+`Tracer` and `get_tracer()` accept the following optional arguments:
+
+ * `elasticapm_client`: an already instantiated Elastic APM client
+ * `config`: a configuration dictionary, which will be used to instantiate a new Elastic APM client,
+ e.g. `{"SERVER_URL": "https://example.org"}`. See <<configuration, configuration>> for more information.
+
+The `Tracer` object mirrors the upstream interface on the
+https://opentelemetry-python.readthedocs.io/en/latest/api/trace.html#opentelemetry.trace.Tracer[OpenTelemetry `Tracer` object.]
+
+
+[float]
+[[opentelemetry-caveats]]
+=== Caveats
+Not all features of the OpenTelemetry API are supported.
+
+Processors, exporters, metrics, logs, span events, and span links are not supported.
+
+Additionally, due to implementation details, the global context API only works
+when a span is included in the activated context, and tokens are not used.
+Instead, the global context works as a stack, and when a context is detached the
+previously-active context will automatically be activated.
+

elasticapm/base.py

@@ -283,17 +283,20 @@ def queue(self, event_type, data, flush=False):
  flush = False
  self._transport.queue(event_type, data, flush)
 
- def begin_transaction(self, transaction_type, trace_parent=None, start=None):
+ def begin_transaction(self, transaction_type, trace_parent=None, start=None, auto_activate=True):
  """
  Register the start of a transaction on the client
 
  :param transaction_type: type of the transaction, e.g. "request"
  :param trace_parent: an optional TraceParent object for distributed tracing
  :param start: override the start timestamp, mostly useful for testing
+ :param auto_activate: whether to set this transaction in execution_context
  :return: the started transaction object
  """
  if self.config.is_recording:
- return self.tracer.begin_transaction(transaction_type, trace_parent=trace_parent, start=start)
+ return self.tracer.begin_transaction(
+ transaction_type, trace_parent=trace_parent, start=start, auto_activate=auto_activate
+ )
 
  def end_transaction(self, name=None, result="", duration=None):
  """
@@ -474,6 +477,12 @@ def _build_msg_for_logging(
  event_data["context"] = context
  if transaction and transaction.labels:
  context["tags"] = deepcopy(transaction.labels)
+ # No intake for otel.attributes, so make them labels
+ if "otel_attributes" in context:
+ if context.get("tags"):
+ context["tags"].update(context.pop("otel_attributes"))
+ else:
+ context["tags"] = context.pop("otel_attributes")
 
  # if '.' not in event_type:
  # Assume it's a builtin

elasticapm/context/base.py

@@ -31,13 +31,41 @@
 
 class BaseContext(object):
  def set_transaction(self, transaction):
+ """
+ Set the transaction for the current execution context
+ """
  raise NotImplementedError
 
  def get_transaction(self, clear=False):
+ """
+ Get the transaction for the current execution context
+
+ If clear=True, also set the transaction to None for the current
+ execution context.
+ """
  raise NotImplementedError
 
  def set_span(self, span):
+ """
+ Set the active span for the current execution context.
+
+ The previously-activated span will be saved to be re-activated later.
+ """
  raise NotImplementedError
 
  def get_span(self):
+ """
+ Get the active span for the current execution context.
+ """
+ raise NotImplementedError
+
+ def unset_span(self, clear_all=False):
+ """
+ De-activate the current span. If a span was previously active, it will
+ become active again.
+
+ Returns the deactivated span.
+
+ If clear_all=True, all spans will be cleared and no span will be active.
+ """
  raise NotImplementedError

elasticapm/context/contextvars.py

@@ -38,9 +38,15 @@
 
 class ContextVarsContext(BaseContext):
  elasticapm_transaction_var = contextvars.ContextVar("elasticapm_transaction_var")
- elasticapm_span_var = contextvars.ContextVar("elasticapm_span_var")
+ elasticapm_spans_var = contextvars.ContextVar("elasticapm_spans_var", default=())
 
  def get_transaction(self, clear=False):
+ """
+ Get the transaction for the current execution context
+
+ If clear=True, also set the transaction to None for the current
+ execution context.
+ """
  try:
  transaction = self.elasticapm_transaction_var.get()
  if clear:
@@ -50,16 +56,45 @@ def get_transaction(self, clear=False):
  return None
 
  def set_transaction(self, transaction):
+ """
+ Set the transaction for the current execution context
+ """
  self.elasticapm_transaction_var.set(transaction)
 
  def get_span(self):
- try:
- return self.elasticapm_span_var.get()
- except LookupError:
- return None
+ """
+ Get the active span for the current execution context.
+ """
+ spans = self.elasticapm_spans_var.get()
+ return spans[-1] if spans else None
 
  def set_span(self, span):
- self.elasticapm_span_var.set(span)
+ """
+ Set the active span for the current execution context.
+
+ The previously-activated span will be saved to be re-activated later.
+ """
+ spans = self.elasticapm_spans_var.get()
+ self.elasticapm_spans_var.set(spans + (span,))
+
+ def unset_span(self, clear_all=False):
+ """
+ De-activate the current span. If a span was previously active, it will
+ become active again.
+
+ Returns the deactivated span.
+
+ If clear_all=True, all spans will be cleared and no span will be active.
+ """
+ spans = self.elasticapm_spans_var.get()
+ span = None
+ if spans:
+ span = spans[-1]
+ if clear_all:
+ self.elasticapm_spans_var.set(())
+ else:
+ self.elasticapm_spans_var.set(spans[0:-1])
+ return span
 
 
 execution_context = ContextVarsContext()