[monitor] README + samples _ ci.yml (#15288)

* README + minor improvs * changes * Update sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/README.md * samples readme * Update sdk/monitor/ci.yml Co-authored-by: Scott Beddall <45376673+scbedd@users.noreply.github.com> * Update sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md Co-authored-by: Leighton Chen <lechen@microsoft.com> * Update sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md Co-authored-by: Leighton Chen <lechen@microsoft.com> * readme * Apply suggestions from code review Co-authored-by: Leighton Chen <lechen@microsoft.com> * Update sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md * comments * conn str Co-authored-by: Scott Beddall <45376673+scbedd@users.noreply.github.com> Co-authored-by: Leighton Chen <lechen@microsoft.com>
Azure · Nov 13, 2020 · 969b0ea · 969b0ea
1 parent 2eea215
commit 969b0ea
Show file tree

Hide file tree

Showing 8 changed files with 230 additions and 63 deletions.
diff --git a/sdk/monitor/ci.yml b/sdk/monitor/ci.yml
@@ -31,5 +31,5 @@ extends:
     Artifacts:
     - name: azure_mgmt_monitor
       safeName: azuremgmtmonitor
-    - name: opentelemetry_exporter_azuremonitor
-      safeName: opentelemetryexporterazuremonitor
+    - name: microsoft_opentelemetry_exporter_azuremonitor
+      safeName: microsoftopentelemetryexporterazuremonitor
diff --git a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/README.md
@@ -1,13 +1,219 @@
-# Azure Opentelemetry Exporter for Monitor
+# Microsoft Opentelemetry exporter for Azure Monitor
+
+[![Gitter chat](https://img.shields.io/gitter/room/Microsoft/azure-monitor-python)](https://gitter.im/Azure/azure-sdk-for-python)
+
+The exporter for Azure Monitor allows you to export tracing data utilizing the OpenTelemetry SDK and send telemetry data to Azure Monitor for applications written in Python.
+
+[Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor) | [Package (PyPi)][pypi] | [API reference documentation][api_docs] | [Product documentation][product_docs] | [Samples](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples) | [Changelog](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/CHANGELOG.md)
+
+> **NOTE**: This is the preview for the next major version of [`opentelemetry-azure-monitor-python`](https://github.com/microsoft/opentelemetry-azure-monitor-python).
 
 ## Getting started
 
+### Install the package
+
+Install the Microsoft Opentelemetry exporter for Azure Monitor with [pip][pip]:
+
+```Bash
+pip install microsoft-opentelemetry-exporter-azuremonitor --pre
+```
+
+### Prerequisites: 
+To use this package, you must have:
+* Azure subscription - [Create a free account][azure_sub]
+* Azure Monitor - [How to use application insights][application_insights_namespace]
+* Opentelemetry SDK - [Opentelemtry SDK for Python][ot_sdk_python]
+* Python 3.5 or later - [Install Python][python]
+
+### Authenticate the client
+
+Interaction with Azure monitor exporter starts with an instance of the `AzureMonitorSpanExporter` class. You will need a **connection_string** to instantiate the object.
+Please find the samples linked below for demonstration as to how to authenticate using a connection string.
+
+#### [Create Exporter from connection string][sample_authenticate_client_connstr]
+
+```Python
+from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter
+exporter = AzureMonitorSpanExporter(
+    connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING "]
+)
+```
+
 ## Key concepts
 
+Some of the key concepts for the Azure monitor exporter include:
+
+* [Opentelemetry][opentelemtry_spec]: Opentelemetry is a set of libraries used to collect and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior.
+
+* [Instrumentation][instrumentation_library]: The ability to call the opentelemetry API directly by any application is facilitated by instrumentaton. A library that enables OpenTelemetry observability for another library is called an Instrumentation Library.
+
+* [Trace][trace_concept]: Trace refers to distributed tracing. It can be thought of as a directed acyclic graph (DAG) of Spans, where the edges between Spans are defined as parent/child relationship.
+
+* [Tracer Provider][tracer_provider]: Provides a `Tracer` for use by the given instrumentation library.
+
+* [Span Processor][span_processor]: A span processor allows hooks for SDK's `Span` start and end method invocations. Follow the link for more information.
+
+* [Sampling][sampler_ref]: Sampling is a mechanism to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend.
+
+* [AzureMonitorSpanExporter][client_reference]: This is the class that is initialized to send tracing related telemetry to Azure Monitor.
+
+* [Exporter Options][exporter_options]: Options to configure Azure exporters. Includes connection_string, instrumentation_key, proxies, timeout etc.
+
+For more information about these resources, see [What is Azure Monitor?][product_docs].
+
 ## Examples
 
+The following sections provide several code snippets covering some of the most common tasks, including:
+
+* [Exporting a custom span](#export-hello-world-trace)
+* [Modifying spans](#modifying-traces)
+* [Using an instrumentation to track a library](#instrumentation-with-requests-library)
+
+
+### Export Hello World Trace
+
+```Python
+import os
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter
+
+exporter = AzureMonitorSpanExporter(
+    connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING "]
+)
+
+trace.set_tracer_provider(TracerProvider())
+tracer = trace.get_tracer(__name__)
+span_processor = BatchExportSpanProcessor(exporter)
+trace.get_tracer_provider().add_span_processor(span_processor)
+
+with tracer.start_as_current_span("hello"):
+    print("Hello, World!")
+```
+
+### Modifying Traces
+
+* You can pass a callback function to the exporter to process telemetry before it is exported.
+* Your callback function can return False if you do not want this envelope exported.
+* Your callback function must accept an envelope data type as its parameter.
+* You can see the schema for Azure Monitor data types in the envelopes here.
+* The AzureMonitorSpanExporter handles Data data types.
+
+```Python
+from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+
+# Callback function to add os_type: linux to span properties
+def callback_function(envelope):
+    envelope.data.baseData.properties['os_type'] = 'linux'
+    return True
+
+exporter = AzureMonitorSpanExporter(
+    connection_string='InstrumentationKey=<your-ikey-here>'
+)
+# This line will modify telemetry
+exporter.add_telemetry_processor(callback_function)
+
+trace.set_tracer_provider(TracerProvider())
+tracer = trace.get_tracer(__name__)
+span_processor = BatchExportSpanProcessor(exporter)
+trace.get_tracer_provider().add_span_processor(span_processor)
+
+with tracer.start_as_current_span('hello'):
+    print('Hello World!')
+```
+
+### Instrumentation with requests library
+
+OpenTelemetry also supports several instrumentations which allows to instrument with third party libraries.
+
+This example shows how to instrument with the [requests](https://pypi.org/project/requests/) library.
+
+* Install the requests integration package using pip install opentelemetry-instrumentation-requests.
+
+```Python
+import os
+import requests
+from opentelemetry import trace
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+
+from microsoft.opentelemetry.exporter.azuremonitor import AzureMonitorSpanExporter
+
+trace.set_tracer_provider(TracerProvider())
+tracer = trace.get_tracer(__name__)
+
+# This line causes your calls made with the requests library to be tracked.
+RequestsInstrumentor().instrument()
+span_processor = BatchExportSpanProcessor(
+    AzureMonitorSpanExporter(
+        connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING "]
+    )
+)
+trace.get_tracer_provider().add_span_processor(span_processor)
+
+RequestsInstrumentor().instrument()
+
+# This request will be traced
+response = requests.get(url="https://azure.microsoft.com/")
+```
+
 ## Troubleshooting
 
+The exporter raises exceptions defined in [Azure Core](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/README.md#azure-core-library-exceptions).
+
 ## Next steps
 
+### More sample code
+
+Please find further examples in the [samples](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples) directory demonstrating common scenarios.
+
+### Additional documentation
+
+For more extensive documentation on the Azure Monitor service, see the [Azure Monitor documentation][product_docs] on docs.microsoft.com.
+
+For detailed overview of Opentelemetry, visit their [overview](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md) page.
+
 ## Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+<!-- LINKS -->
+[azure_cli]: https://docs.microsoft.com/cli/azure
+[api_docs]: https://aka.ms/monitorexporterapidocs
+[product_docs]: https://docs.microsoft.com/azure/azure-monitor/overview
+[azure_portal]: https://portal.azure.com
+[azure_sub]: https://azure.microsoft.com/free/
+[cloud_shell]: https://docs.microsoft.com/azure/cloud-shell/overview
+[cloud_shell_bash]: https://shell.azure.com/bash
+[pip]: https://pypi.org/project/pip/
+[pypi]: https://pypi.org/project/opentelemetry-azure-monitor/
+[python]: https://www.python.org/downloads/
+[venv]: https://docs.python.org/3/library/venv.html
+[virtualenv]: https://virtualenv.pypa.io
+[ot_sdk_python]: https://github.com/open-telemetry/opentelemetry-python
+[application_insights_namespace]: https://docs.microsoft.com/azure/azure-monitor/app/app-insights-overview#how-do-i-use-application-insights
+[exporter_options]: https://opentelemetry-azure-monitor-python.readthedocs.io/en/latest/azure_monitor/export/export.options.html?highlight=options
+[trace_concept]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#trace
+[client_reference]: https://opentelemetry-azure-monitor-python.readthedocs.io/en/latest/azure_monitor/export/export.trace.html#module-azure_monitor.export.trace
+[opentelemtry_spec]: https://opentelemetry.io/
+[instrumentation_library]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#instrumentation-libraries
+[tracer_provider]: https://opentelemetry-python.readthedocs.io/en/stable/api/trace.html?highlight=TracerProvider#opentelemetry.trace.TracerProvider
+[span_processor]: https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/trace.html?highlight=SpanProcessor#
+[sampler_ref]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#sampling
+
+[sample_authenticate_client_connstr]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_trace.py#L18
diff --git a/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/README.md b/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/README.md
@@ -1,52 +1,16 @@
-
-## Installation
-
-```sh
-$ pip install opentelemetry-azure-monitor
-```
-
-## Run the Applications
-
-### Trace
-
-* Update the code in trace.py to use your `INSTRUMENTATION_KEY`
-
-* Run the sample
-
-```sh
-$ # from this directory
-$ python trace.py
-```
-
-### Request
-
-* Update the code in request.py to use your `INSTRUMENTATION_KEY`
-
-* Run the sample
-
-```sh
-$ pip install opentelemetry-instrumentation-requests
-$ # from this directory
-$ python request.py
-```
-
-### Server
-
-* Update the code in server.py to use your `INSTRUMENTATION_KEY`
-
-* Run the sample
-
-```sh
-$ pip install opentelemetry-instrumentation-requests
-$ pip install opentelemetry-instrumentation-wsgi
-$ # from this directory
-$ python server.py
-```
-
-* Open http://localhost:8080/ 
-
-
-## Explore the data
-
-After running the applications, data would be available in [Azure](
-https://docs.microsoft.com/azure/azure-monitor/app/app-insights-overview#where-do-i-see-my-telemetry)
+---
+page_type: sample
+languages:
+  - python
+products:
+  - microsoft-opentelemetry-exporter-azuremonitor
+---
+
+# Microsoft Azure Monitor Opentelemetry Exporter Python Samples
+
+These code samples show common champion scenario operations with the AzureMonitorSpanExporter.
+
+* Trace: [sample_trace.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_trace.py)
+* Client: [sample_client.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_client.py)
+* Request: [sample_request.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_request.py)
+* Server: [sample_server.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/microsoft-opentelemetry-exporter-azuremonitor/samples/traces/sample_server.py)
diff --git a/...ter-azuremonitor/samples/traces/client.py → ...remonitor/samples/traces/sample_client.py b/...ter-azuremonitor/samples/traces/client.py → ...remonitor/samples/traces/sample_client.py
@@ -1,8 +1,5 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
-# pylint: disable=import-error
-# pylint: disable=no-member
-# pylint: disable=no-name-in-module
 import os
 import requests
 from opentelemetry import trace
@@ -17,7 +14,7 @@
 RequestsInstrumentor().instrument()
 span_processor = BatchExportSpanProcessor(
     AzureMonitorSpanExporter(
-        connection_string = os.environ["AZURE_MONITOR_CONNECTION_STRING"]
+        connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
     )
 )
 trace.get_tracer_provider().add_span_processor(span_processor)

diff --git a/...er-azuremonitor/samples/traces/request.py → ...emonitor/samples/traces/sample_request.py b/...er-azuremonitor/samples/traces/request.py → ...emonitor/samples/traces/sample_request.py
@@ -17,7 +17,7 @@
 RequestsInstrumentor().instrument()
 span_processor = SimpleExportSpanProcessor(
     AzureMonitorSpanExporter(
-        connection_string = os.environ["AZURE_MONITOR_CONNECTION_STRING"]
+        connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
     )
 )
 trace.get_tracer_provider().add_span_processor(span_processor)

diff --git a/...ter-azuremonitor/samples/traces/server.py → ...remonitor/samples/traces/sample_server.py b/...ter-azuremonitor/samples/traces/server.py → ...remonitor/samples/traces/sample_server.py
@@ -20,7 +20,7 @@
 tracer = trace.get_tracer(__name__)
 
 exporter = AzureMonitorSpanExporter(
-    connection_string = os.environ["AZURE_MONITOR_CONNECTION_STRING"]
+    connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
 )
 
 # SpanExporter receives the spans and send them to the target location.

diff --git a/...rter-azuremonitor/samples/traces/trace.py → ...uremonitor/samples/traces/sample_trace.py b/...rter-azuremonitor/samples/traces/trace.py → ...uremonitor/samples/traces/sample_trace.py
@@ -15,7 +15,7 @@ def callback_function(envelope):
 
 
 exporter = AzureMonitorSpanExporter(
-    connection_string = os.environ["AZURE_MONITOR_CONNECTION_STRING"]
+    connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
 )
 exporter.add_telemetry_processor(callback_function)
 

diff --git a/sdk/monitor/tests.yml b/sdk/monitor/tests.yml
@@ -5,7 +5,7 @@ jobs:
     parameters:
       ServiceDirectory: monitor
       TestTimeoutInMinutes: 300
-      BuildTargetingString: opentelemetry-exporter-azuremonitor
+      BuildTargetingString: microsoft-opentelemetry-exporter-azuremonitor
       EnvVars:
         AZURE_SUBSCRIPTION_ID: $(azure-subscription-id)
         AZURE_TENANT_ID: $(aad-azure-sdk-test-tenant-id)