Add back opentracing docs (#1512)

Author: basepi

docs/opentracing.asciidoc

@@ -0,0 +1,130 @@
+// TODO This doc should be removed in 7.0.0
+// It continues to exist because older versions point to the latest version on a major
+[[opentracing-bridge]]
+== OpenTracing API
+
+The Elastic APM OpenTracing bridge allows you to create Elastic APM `Transactions` and `Spans`,
+using the OpenTracing API.
+In other words,
+it translates calls to the OpenTracing API to Elastic APM events, which allows for the reuse of existing instrumentation.
+
+The first span of a service will be converted to an Elastic APM
+{apm-guide-ref}/transactions.html[`Transaction`],
+subsequent spans are mapped to Elastic APM
+{apm-guide-ref}/transaction-spans.html[`Span`].
+
+[float]
+[[opentracing-getting-started]]
+=== Getting started
+The first step in getting started with the OpenTracing API bridge is to install the `opentracing` library:
+
+[source,bash]
+----
+pip install elastic-apm[opentracing]
+----
+
+Or if you already have installed `elastic-apm`
+
+
+[source,bash]
+----
+pip install opentracing>=2.0.0
+----
+
+
+[float]
+[[opentracing-init-tracer]]
+=== Initialize tracer
+
+[source,python]
+----
+from elasticapm.contrib.opentracing import Tracer
+
+tracer = Tracer();
+----
+
+`Tracer` accepts the following optional arguments:
+
+  * `client_instance`: 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.
+  * `scope_manager`: a scope manager instance. Defaults to `ThreadLocalScopeManager` (see
+
+
+[float]
+[[opentracing-elastic-apm-tags]]
+=== Elastic APM specific tags
+
+Elastic APM defines some tags which are not included in the OpenTracing API but are relevant in the context of Elastic APM.
+
+- `type` - sets the type of the transaction,
+  for example `request`, `ext` or `db`
+- `user.id` - sets the user id,
+  appears in the "User" tab in the transaction details in the Elastic APM UI
+- `user.email` - sets the user email,
+  appears in the "User" tab in the transaction details in the Elastic APM UI
+- `user.username` - sets the user name,
+  appears in the "User" tab in the transaction details in the Elastic APM UI
+- `result` - sets the result of the transaction. Overrides the default value of `success`.
+
+NOTE: these tags need to be set on the first span of an operation (e.g. an incoming request of your webapp).
+
+[float]
+[[opentracing-caveats]]
+=== Caveats
+Not all features of the OpenTracing API are supported.
+
+[float]
+[[opentracing-scope-managers]]
+==== Scope Managers
+Currently, only the `ThreadLocalScopeManager` is supported.
+Using other scope managers will lead to unpredictable and possibly app-breaking behavior.
+
+[float]
+[[opentracing-instrumentation]]
+==== Instrumentation
+
+It is recommended to not use the built-in instrumentations of Elastic APM together with third-party OpenTracing instrumentations
+like https://pypi.org/project/opentracing_instrumentation/[opentracing_instrumentation] in the same service.
+If you would like to use such instrumentations, we recommend to disable the built-in instrumentation using the <<config-instrument,`instrument`>> config option.
+
+[float]
+[[opentracing-propagation]]
+==== Context propagation
+This bridge only supports the formats `Format.Builtin.TEXT_MAP` and `Format.Builtin.HTTP_HEADERS`.
+`Format.Builtin.BINARY` is currently not supported.
+
+[float]
+[[opentracing-references]]
+==== Span references
+Currently, this bridge only supports `child_of` references.
+Other references,
+like `follows_from` are not supported yet.
+
+[float]
+[[opentracing-baggage]]
+==== Baggage
+The `Span.set_baggage_item(key, value)` method is not supported.
+Baggage items are silently dropped.
+
+[float]
+[[opentracing-logs]]
+==== Logs
+Only exception logging is supported.
+Logging an Exception on the OpenTracing span will create an Elastic APM
+{apm-guide-ref}/errors.html[`Error`].
+Example:
+
+[source,python]
+----
+with tracer.start_active_span("transaction") as tx_scope:
+    try:
+        raise ValueError("oops")
+    except ValueError:
+        exc_type, exc_val, exc_tb = sys.exc_info()[:3]
+        tx_scope.span.log_kv({
+            "python.exception.type": exc_type,
+            "python.exception.val": exc_val,
+            "python.exception.tb": exc_tb
+        })
+----