Version bump for 0.5.dev0 on master (open-telemetry#443)

Rename TracerSource to TracerProvider (open-telemetry#441)

Following discussion in open-telemetry#434, align the name with the specification.

Co-authored-by: Chris Kleinknecht <libc@google.com>

Fix new ext READMEs (open-telemetry#444)

Some of the new ext packages had ReStructuredText errors. PyPI rejected the uploads for these packages with:

HTTPError: 400 Client Error: The description failed to render for 'text/x-rst'. See https://pypi.org/help/#description-content-type for more information. for url: https://upload.pypi.org/legacy/

Adding attach/detach methods as per spec (open-telemetry#429)

This change updates the Context API with the following:

- removes the remove_value method
- removes the set_current method
- adds attach and detach methods

Fixes open-telemetry#420

Co-authored-by: Chris Kleinknecht <libc@google.com>

Make Counter and MinMaxSumCount aggregators thread safe (open-telemetry#439)

OT Collector trace exporter (open-telemetry#405)

Based on the OpenCensus agent exporter.

Fixes open-telemetry#343

Co-authored-by: Chris Kleinknecht <libc@google.com>

API: Renaming TraceOptions to TraceFlags (open-telemetry#450)

Renaming TraceOptions to TraceFlags, which is the term used to describe the
flags associated with the trace in the OpenTelemetry specification.

Closes open-telemetry#434

api: Implement "named" meters + Remove "Batcher" from Meter constructor (open-telemetry#431)

Implements open-telemetry#221.
Also fixes open-telemetry#394.

Stateful.py and stateless.py in metrics example folder are not changed to use the new loader in anticipation of open-telemetry#422 being merged first and removing them.

Lastly, moves InstrumentationInfo from trace.py in the sdk to utils.

Prepare to host on readthedocs.org (open-telemetry#452)

sdk: Implement observer instrument (open-telemetry#425)

Observer instruments are used to capture a current set of values at a point in
time [1].

This commit extends the Meter interface to allow to register an observer
instrument by pasing a callback that will be executed at collection time.
The logic inside collection is updated to consider these instruments and
a new ObserverAggregator is implemented.

[1] https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/api-metrics.md#observer-instruments

sdk: fix ConsoleSpanExporter (open-telemetry#455)

19d573a ("Add io and formatter options to console exporter (open-telemetry#412)")
changed the way spans are printed by using write() instead of print().
In Python 3.x sys.stdout is line-buffered, so the spans were not being printed
to the console at the right timing.

This commit fixes that by adding an explicit flush() call at the end of the
export function , it also changes the default formatter to include a line break.

To be precise, only one of the changes was needed to solve the problem, but as
a matter of completness both are included, i.e, to handle the case where the
formatter chosen by the user doesn't append a line break.

jaeger: Usage README Update for opentelemetry-ext-jaeger (open-telemetry#459)

Usage docs for opentelemetry-ext-jaeger need to be updated after the change to `TracerSource` with v0.4. Looks like it was partially updated already.

Users following the usage docs will currently run into this error:
`AttributeError: 'Tracer' object has no attribute 'add_span_processor'`

api: Implementing Propagators API to use Context  (open-telemetry#446)

Implementing Propagators API to use Context.

Moving tracecontexthttptextformat to trace/propagation, as TraceContext is specific to trace rather that broader context propagation.

Using attach/detach for wsgi and flask extensions, enabling activation of the full context rather that activating of a sub component such as traces.

Adding a composite propagator.

Co-authored-by: Mauricio Vásquez <mauricio@kinvolk.io>

.readthedocs.yml

@@ -0,0 +1,14 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+build:
+  image: latest
+
+python:
+  version: 3.8
+  install:
+    - requirements: docs-requirements.txt

README.md

@@ -51,12 +51,12 @@ pip install -e ./ext/opentelemetry-ext-{integration}
 
 ```python
 from opentelemetry import trace
-from opentelemetry.sdk.trace import TracerSource
+from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import ConsoleSpanExporter
 from opentelemetry.sdk.trace.export import SimpleExportSpanProcessor
 
-trace.set_preferred_tracer_source_implementation(lambda T: TracerSource())
-trace.tracer_source().add_span_processor(
+trace.set_preferred_tracer_provider_implementation(lambda T: TracerProvider())
+trace.tracer_provider().add_span_processor(
     SimpleExportSpanProcessor(ConsoleSpanExporter())
 )
 tracer = trace.get_tracer(__name__)
@@ -70,12 +70,14 @@ with tracer.start_as_current_span('foo'):
 
 ```python
 from opentelemetry import metrics
-from opentelemetry.sdk.metrics import Counter, Meter
+from opentelemetry.sdk.metrics import Counter, MeterProvider
 from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+from opentelemetry.sdk.metrics.export.controller import PushController
 
-metrics.set_preferred_meter_implementation(lambda T: Meter())
-meter = metrics.meter()
+metrics.set_preferred_meter_provider_implementation(lambda _: MeterProvider())
+meter = metrics.get_meter(__name__)
 exporter = ConsoleMetricsExporter()
+controller = PushController(meter, exporter, 5)
 
 counter = meter.create_metric(
     "available memory",
@@ -89,9 +91,6 @@ counter = meter.create_metric(
 label_values = ("staging",)
 counter_handle = counter.get_handle(label_values)
 counter_handle.add(100)
-
-exporter.export([(counter, label_values)])
-exporter.shutdown()
 ```
 
 See the [API documentation](https://open-telemetry.github.io/opentelemetry-python/) for more detail, and the [examples folder](./examples) for a more sample code.

docs-requirements.txt

@@ -0,0 +1,10 @@
+sphinx~=2.4
+sphinx-rtd-theme~=0.4
+sphinx-autodoc-typehints~=1.10.2
+
+# Required by ext packages
+opentracing~=2.2.0
+Deprecated>=1.2.6
+thrift>=0.10.0
+pymongo~=3.1
+flask~=1.0

docs/opentelemetry.sdk.metrics.rst

@@ -8,6 +8,7 @@ Submodules
 
    opentelemetry.sdk.metrics.export.aggregate
    opentelemetry.sdk.metrics.export.batcher
+   opentelemetry.sdk.util.instrumentation
 
 .. automodule:: opentelemetry.sdk.metrics
     :members:

docs/opentelemetry.sdk.trace.rst

@@ -7,6 +7,7 @@ Submodules
 .. toctree::
 
    opentelemetry.sdk.trace.export
+   opentelemetry.sdk.util.instrumentation
 
 .. automodule:: opentelemetry.sdk.trace
     :members:

docs/opentelemetry.sdk.util.instrumentation.rst

@@ -0,0 +1,4 @@
+opentelemetry.sdk.util.instrumentation
+==========================================
+
+.. automodule:: opentelemetry.sdk.util.instrumentation

examples/basic_tracer/README.md

@@ -53,6 +53,26 @@ Click on the trace to view its details.
 
 <p align="center"><img src="./images/jaeger-ui-detail.png?raw=true"/></p>
 
+### Collector
+
+* Start Collector
+
+```sh
+$ pip install docker-compose
+$ cd docker
+$ docker-compose up
+
+* Run the sample
+
+$ pip install opentelemetry-ext-otcollector
+$ # from this directory
+$ EXPORTER=collector python tracer.py
+```
+
+Collector is configured to export to Jaeger, follow Jaeger UI isntructions to find the traces.
+
+
+
 ## Useful links
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For more information on tracing in Python, visit: <https://github.com/open-telemetry/opentelemetry-python>

examples/basic_tracer/docker/collector-config.yaml

@@ -0,0 +1,19 @@
+receivers:
+  opencensus:
+    endpoint: "0.0.0.0:55678"
+
+exporters:
+  jaeger_grpc:
+    endpoint: jaeger-all-in-one:14250
+  logging: {}
+
+processors:
+  batch:
+  queued_retry:
+
+service:
+  pipelines:
+    traces:
+      receivers: [opencensus]
+      exporters: [jaeger_grpc, logging]
+      processors: [batch, queued_retry]

examples/basic_tracer/docker/docker-compose.yaml

@@ -0,0 +1,20 @@
+version: "2"
+services:
+
+  # Collector
+  collector:
+    image: omnition/opentelemetry-collector-contrib:latest
+    command: ["--config=/conf/collector-config.yaml", "--log-level=DEBUG"]
+    volumes:
+      - ./collector-config.yaml:/conf/collector-config.yaml
+    ports:
+      - "55678:55678"
+
+  jaeger-all-in-one:
+    image: jaegertracing/all-in-one:latest
+    ports:
+      - "16686:16686"
+      - "6831:6831/udp"
+      - "6832:6832/udp"
+      - "14268"
+      - "14250"

examples/basic_tracer/tracer.py

@@ -17,7 +17,7 @@
 import os
 
 from opentelemetry import trace
-from opentelemetry.sdk.trace import TracerSource
+from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import (
     BatchExportSpanProcessor,
     ConsoleSpanExporter,
@@ -26,17 +26,28 @@
 if os.getenv("EXPORTER") == "jaeger":
     from opentelemetry.ext.jaeger import JaegerSpanExporter
 
+    print("Using JaegerSpanExporter")
     exporter = JaegerSpanExporter(
         service_name="basic-service",
         agent_host_name="localhost",
         agent_port=6831,
     )
+elif os.getenv("EXPORTER") == "collector":
+    from opentelemetry.ext.otcollector.trace_exporter import (
+        CollectorSpanExporter,
+    )
+
+    print("Using CollectorSpanExporter")
+    exporter = CollectorSpanExporter(
+        service_name="basic-service", endpoint="localhost:55678"
+    )
 else:
+    print("Using ConsoleSpanExporter")
     exporter = ConsoleSpanExporter()
 
 # The preferred tracer implementation must be set, as the opentelemetry-api
 # defines the interface with a no-op implementation.
-trace.set_preferred_tracer_source_implementation(lambda T: TracerSource())
+trace.set_preferred_tracer_provider_implementation(lambda T: TracerProvider())
 
 # We tell OpenTelemetry who it is that is creating spans. In this case, we have
 # no real name (no setup.py), so we make one up. If we had a version, we would
@@ -46,7 +57,7 @@
 # SpanExporter receives the spans and send them to the target location.
 span_processor = BatchExportSpanProcessor(exporter)
 
-trace.tracer_source().add_span_processor(span_processor)
+trace.tracer_provider().add_span_processor(span_processor)
 with tracer.start_as_current_span("foo"):
     with tracer.start_as_current_span("bar"):
         with tracer.start_as_current_span("baz"):

examples/http/server.py

@@ -22,7 +22,7 @@
 from opentelemetry import trace
 from opentelemetry.ext import http_requests
 from opentelemetry.ext.wsgi import OpenTelemetryMiddleware
-from opentelemetry.sdk.trace import TracerSource
+from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import (
     BatchExportSpanProcessor,
     ConsoleSpanExporter,
@@ -41,17 +41,17 @@
 
 # The preferred tracer implementation must be set, as the opentelemetry-api
 # defines the interface with a no-op implementation.
-trace.set_preferred_tracer_source_implementation(lambda T: TracerSource())
+trace.set_preferred_tracer_provider_implementation(lambda T: TracerProvider())
 tracer = trace.get_tracer(__name__)
 
 # SpanExporter receives the spans and send them to the target location.
 span_processor = BatchExportSpanProcessor(exporter)
-trace.tracer_source().add_span_processor(span_processor)
+trace.tracer_provider().add_span_processor(span_processor)
 
 # Integrations are the glue that binds the OpenTelemetry API and the
 # frameworks and libraries that are used together, automatically creating
 # Spans and propagating context as appropriate.
-http_requests.enable(trace.tracer_source())
+http_requests.enable(trace.tracer_provider())
 app = flask.Flask(__name__)
 app.wsgi_app = OpenTelemetryMiddleware(app.wsgi_app)
 

examples/http/tracer_client.py

@@ -20,7 +20,7 @@
 
 from opentelemetry import trace
 from opentelemetry.ext import http_requests
-from opentelemetry.sdk.trace import TracerSource
+from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import (
     BatchExportSpanProcessor,
     ConsoleSpanExporter,
@@ -39,15 +39,15 @@
 
 # The preferred tracer implementation must be set, as the opentelemetry-api
 # defines the interface with a no-op implementation.
-trace.set_preferred_tracer_source_implementation(lambda T: TracerSource())
-tracer_source = trace.tracer_source()
+trace.set_preferred_tracer_provider_implementation(lambda T: TracerProvider())
+tracer_provider = trace.tracer_provider()
 
 # SpanExporter receives the spans and send them to the target location.
 span_processor = BatchExportSpanProcessor(exporter)
-tracer_source.add_span_processor(span_processor)
+tracer_provider.add_span_processor(span_processor)
 
 # Integrations are the glue that binds the OpenTelemetry API and the
 # frameworks and libraries that are used together, automatically creating
 # Spans and propagating context as appropriate.
-http_requests.enable(tracer_source)
+http_requests.enable(tracer_provider)
 response = requests.get(url="http://127.0.0.1:5000/")

examples/metrics/observer_example.py

@@ -0,0 +1,72 @@
+# Copyright 2020, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+This example shows how the Observer metric instrument can be used to capture
+asynchronous metrics data.
+"""
+import psutil
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import LabelSet, MeterProvider
+from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
+from opentelemetry.sdk.metrics.export.batcher import UngroupedBatcher
+from opentelemetry.sdk.metrics.export.controller import PushController
+
+# Configure a stateful batcher
+batcher = UngroupedBatcher(stateful=True)
+
+metrics.set_preferred_meter_provider_implementation(lambda _: MeterProvider())
+meter = metrics.get_meter(__name__)
+
+# Exporter to export metrics to the console
+exporter = ConsoleMetricsExporter()
+
+# Configure a push controller
+controller = PushController(meter=meter, exporter=exporter, interval=2)
+
+
+# Callback to gather cpu usage
+def get_cpu_usage_callback(observer):
+    for (number, percent) in enumerate(psutil.cpu_percent(percpu=True)):
+        label_set = meter.get_label_set({"cpu_number": str(number)})
+        observer.observe(percent, label_set)
+
+
+meter.register_observer(
+    callback=get_cpu_usage_callback,
+    name="cpu_percent",
+    description="per-cpu usage",
+    unit="1",
+    value_type=float,
+    label_keys=("cpu_number",),
+)
+
+
+# Callback to gather RAM memory usage
+def get_ram_usage_callback(observer):
+    ram_percent = psutil.virtual_memory().percent
+    observer.observe(ram_percent, LabelSet())
+
+
+meter.register_observer(
+    callback=get_ram_usage_callback,
+    name="ram_percent",
+    description="RAM memory usage",
+    unit="1",
+    value_type=float,
+    label_keys=(),
+)
+
+input("Press a key to finish...\n")

examples/metrics/prometheus.py

@@ -21,15 +21,15 @@
 
 from opentelemetry import metrics
 from opentelemetry.ext.prometheus import PrometheusMetricsExporter
-from opentelemetry.sdk.metrics import Counter, Meter
+from opentelemetry.sdk.metrics import Counter, MeterProvider
 from opentelemetry.sdk.metrics.export.controller import PushController
 
 # Start Prometheus client
 start_http_server(port=8000, addr="localhost")
 
 # Meter is responsible for creating and recording metrics
-metrics.set_preferred_meter_implementation(lambda _: Meter())
-meter = metrics.meter()
+metrics.set_preferred_meter_provider_implementation(lambda _: MeterProvider())
+meter = metrics.get_meter(__name__)
 # exporter to export metrics to Prometheus
 prefix = "MyAppPrefix"
 exporter = PrometheusMetricsExporter(prefix)