Update OTel tutorial. (#169)

* Update OTel tutorial.

Signed-off-by: Hannah Troisi <htroisi@pixielabs.ai>

* Address aimichelle's comments.

Signed-off-by: Hannah Troisi <htroisi@pixielabs.ai>

* Update Plugin docs.

Signed-off-by: Hannah Troisi <htroisi@pixielabs.ai>

* tweak

Signed-off-by: Hannah Troisi <htroisi@pixielabs.ai>

Author: htroisi

content/assets/plugin/data-export-icon.png

@@ -21,7 +21,7 @@ Pixie’s edge compute engine allows us to apply ML/AI on unsampled data. We wil
 
 ### Support the ecosystem
 
-Pixie has a versatile execution engine which can ingest and export data in a variety of formats. We plan to export and ingest data in the OpenTelemetry format which will enable developers to consume Pixie data along with the data produced by other tools (Jaeger, Prometheus). We also plan to leverage our [client APIs](/reference/api) in order to support tighter integrations with other open source projects.
+Pixie has a versatile execution engine which can ingest and export data in a variety of formats. Pixie currently supports [exporting data in the OpenTelemetry format](/tutorials/integrations/otel/) which enables developers to consume Pixie data along with data produced by other tools (Jaeger, Prometheus. We plan to add ingest in the future. We also plan to leverage our [client APIs](/reference/api) in order to support tighter integrations with other open source projects.
 
 ### Non-goals
 

content/assets/plugin/data-export.png

@@ -128,11 +128,7 @@ Go, C++ and Rust are currently supported. The [Roadmap](/about-pixie/roadmap) co
 
 ### How do I export data from the Pixie platform? Import data?
 
-Pixie offers two [client libraries](/reference/api/overview/) (Go, Python) to allow developers to easily integrate Pixie observability data into their existing stack.
-
-Pixie does not currently offer data ingestion.
-
-The [Roadmap](/about-pixie/roadmap) contains plans to support exporting or ingesting data in a variety of additional formats.
+Pixie offers two [client libraries](/reference/api/overview/) (Go, Python) to allow developers to easily integrate Pixie observability data into their existing stack. You can also use Pixie's [Plugin System](/reference/plugins/plugin-system/) to [export data in the OpenTelemetry format](/tutorials/integrations/otel/). Pixie does not currently offer data ingestion. The [Roadmap](/about-pixie/roadmap) contains plans to support exporting or ingesting data in a variety of additional formats.
 
 ### How do I share a Pixie dashboard with others?
 

content/assets/plugin/otel-script-output.png

@@ -1,22 +1,41 @@
 ---
-title: "Export Data to OpenTelemetry"
-metaTitle: "Tutorials | Integrations and Alerts | Pixie <> OpenTelemetry"
-metaDescription: "Export Data to OpenTelemetry"
+title: "Export OpenTelemetry Data"
+metaTitle: "Tutorials | Integrations and Alerts | Export OpenTelemetry Data"
+metaDescription: "Export OpenTelemetry Data"
 order: 3
 redirect_from:
     - /tutorials/otel/
 ---
 
+This tutorial will demonstrate how to export Pixie data in the OpenTelemetry (OTel) format.
 
-Pixie comes packaged with an OpenTelemetry exporter. You can write PxL scripts that define the transformation of Pixie DataFrames into OpenTelemetry data. This article walks through a script that exports HTTP data collected by Pixie into an OpenTelemetry endpoint. More detailed PxL documentation for the OpenTelemetry integration is available [here](/reference/pxl/otel-export). 
+To do this, we will take the following steps:
 
+1. Deploy an OTel collector to our cluster.
+2. Write a PxL script that uses the [OTel methods](/reference/pxl/otel-export/) to transformation Pixie DataFrames into OTel data.
+3. Setup the Pixie [Plugin System](/reference/plugins/plugin-system/) to run the PxL script at regularly scheduled intervals.
 
-## Example OpenTelemetry Export PxL Script
+Note that [Pixie's API](/using-pixie/api-quick-start/) can also be used to run the PxL scripts developed in Step 2, however this tutorial will cover the Plugin System only.
 
-The following [PxL script](/tutorials/pxl-scripts/write-pxl-scripts/#overview) calculates the rate of HTTP requests made to each pod in your cluster and exports that data as an OpenTelemetry Gauge metric.  
+## Deploy the OTel Collector
 
+If you don't already have an OTel collector set up, you can follow the directions to deploy our demo collector [here](https://github.com/pixie-io/pixie-demos/tree/main/otel-collector).
 
-```python
+Most OTel collectors are configured to forward metrics to _other tools_ such as Prometheus or Jaeger. For the sake of this tutorial, our demo collector simply outputs the metrics it receives to its logs.
+
+## Write the PxL script
+
+PxL scripts are used to query telemetry data collected by the Pixie Platform. Our PxL script will also export the Pixie data in the OTel format. We'll use the Live UI's `Scratch Pad` to develop our PxL script.
+
+1. Open Pixie's [Live UI](/using-pixie/using-live-ui/).
+
+2. Select the `Scratch Pad` script from the `script` drop-down menu in the top left.
+
+3. Open the script editor using the keyboard shortcut: `ctrl+e` (Windows, Linux) or `cmd+e` (Mac).
+
+4. Replace the contents of the `PxL Script` tab with the following. Hover over the code block below to show the copy button in the top-right.
+
+```python:numbers
 import px
 # Read in the http_events table
 df = px.DataFrame(table='http_events', start_time='-10s')
@@ -36,10 +55,8 @@ df.requests_per_s = df.throughput / 10
 px.export(df, px.otel.Data(
   # endpoint arg not required if run in a plugin that provides the endpoint
   endpoint=px.otel.Endpoint(
-    url='0.0.0.0:98765',
-    headers={
-      'apikey': '12345',
-    }
+    url='otel-collector.default.svc.cluster.local:4317',
+    insecure=True
   ),
   resource={
       # service.name is required by OpenTelemetry.
@@ -58,13 +75,31 @@ px.export(df, px.otel.Data(
     )
   ]
 ))
+
+px.display(df)
 ```
 
+5. Run the script using the `RUN` button in the top right or by using the keyboard shortcut: `ctrl+enter` (Windows, Linux) or `cmd+enter` (Mac).
+
+6. Hide the script editor using `ctrl+e` (Windows, Linux) or `cmd+e` (Mac).
+
+> Your Live UI should output something similar to the following:
 
+<svg title='OTel PxL script output in the Live UI' src='plugin/otel-script-output.png'/>
 
-## The Data
-The first part of this script (lines 1-19) read  in the `http_events` data and count the number of requests made to each pod from the last 10s.
+> This PxL script calculates the rate of HTTP requests made to each pod in your cluster and exports that data as an OTel Gauge metric.
 
+7. To validate that the data has been received by the OTel collector, check logs for the the `otel-collector-*` pod. If the export was successful, you should see logs similar to:
+
+```bash
+2022-04-15T20:48:20.633Z    INFO    loggingexporter/logging_exporter.go:54    MetricsExporter    {"#metrics": 32}
+```
+
+> If this is your first PxL script, you may want to check out the [Writing a PxL Script Tutorial](/tutorials/pxl-scripts/write-pxl-scripts/) to learn more. We'll give a high-level overview of this script below.
+
+### The Data
+
+The first part of the PxL script (lines 1-19) read in the `http_events` data and count the number of requests made to each pod from the last 10s.
 
 ```python
 import px
@@ -86,50 +121,39 @@ df = df.groupby(['pod', 'service', 'req_path']).agg(
 df.requests_per_s = df.throughput / 10
 ```
 
+### Exporting
 
-
-## Exporting
-
-To export the data, you’ll call `px.export` with the DataFrame as the first argument and the export target `px.otel.Data` as the second argument. 
-
+To export the data, you’ll call `px.export` with the DataFrame as the first argument and the export target `px.otel.Data` as the second argument.
 
 ```python
 px.export(df, px.otel.Data(...))
 ```
 
-
 The export target (`px.otel.Data`) describes which columns to use for the corresponding OpenTelemetry fields. You specify a column using the same syntax as in a regular query: `df.column_name` or `df[‘column_name’]`. The columns must reference a column available in the `df` argument or the PxL compiler will throw an error
 
-
-## Specifying a Collector Endpoint and Authentication
+### Specifying a Collector Endpoint and Authentication
 
 The PxL OpenTelemetry exporter needs to talk with a collector. You must specify this information via the `endpoint` parameter:
 
-
 ```python
 endpoint=px.otel.Endpoint(
-  url='0.0.0.0:55690',
-  headers={
-    'api-key': '12345',
-  }
+  url='otel-collector.default.svc.cluster.local:4317',
+  insecure=True
 ),
 ```
 
+The endpoint url must be an OpenTelemetry gRPC endpoint. If the OpenTelemetry gRPC endpoint is not secured with SSL, you can set `insecure=True`. Don’t specify a protocol prefix. Optionally, you can also specify the headers passed to the endpoint. Some OpenTelemetry collector providers look for authentication tokens or api keys in the connection context. The headers field is where you can add this information.
 
-The endpoint url must be an OpenTelemetry grpc endpoint and must be secured with SSL. Don’t specify a protocol prefix. Optionally, you can also specify the headers passed to the endpoint. Some OpenTelemetry collector providers look for authentication tokens or api keys in the connection context. The headers field is where you can add this information.
+Note that if you’re writing a [plugin script](/reference/plugins/plugin-system), this information will be passed in by the plugin context and should not be specified. We'll remove this endpoint parameter when we set up the Plugin in Step 3.
 
-Note that if you’re writing a [plugin script](/reference/plugins/plugin-system), this information should be passed in from the plugin context.
-
-
-## Transforming Data
+### Transforming Data
 
 The core idea of the PxL OpenTelemetry export is that you’re converting columnar data from a Pixie DataFrame into the fields of whatever OpenTelemetry data that you wish to capture. You can reference a column by using the attribute syntax `df.column_name`. Under the hood, Pixie will convert the values for each row into a new OpenTelemetry message. The columns must match up with the DataFrame that you are exporting (the first argument to `px.export`), otherwise you will receive a compiler error.
 
-
-## Specifying a Resource
+### Specifying a Resource
 
 The `resource` parameter defines the entity producing the [telemetry data](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md). Users define the `resource` argument as a dictionary mapping attribute keys to the STRING columns that populate the attribute values. The PxL configuration expects `service.name` to be set, all other attributes are optional.
- 
+
 When creating new attribute keys, keep in mind OpenTelemetry has a [recommended pattern](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#document-conventions) that you should follow to maintain broad compatibility with OpenTelemetry collectors.
 
 ```python
@@ -141,13 +165,10 @@ resource={
 },
 ```
 
-
-
-## Specifying Data
+### Specifying Data
 
 The data parameter allows you to specify a list of metrics or traces that are generated from the DataFrame. In the example script, we specify a single Gauge metric for the `df.request_per_s` column. We also supply an attribute for the metric, `req_path`. Each Metric and Trace type supports a custom attribute field. Metric/Trace attributes work similarly to Resource attributes, but they are scoped only to the specific method
 
-
 ```python
 data=[
   px.otel.metric.Gauge(
@@ -161,6 +182,94 @@ data=[
 ]
 ```
 
-
 We currently support a limited set of OpenTelemetry signal types: `metric.Gauge`, `metric.Summary` and `trace.Span`. We also support a subset of the available fields for each instrument. You can see the full set of features [in our api documentation.](/reference/pxl/otel-export) If you want support for other fields, please [open an issue](https://github.com/pixie-io/pixie).
 
+## Setup the Plugin
+
+Now that we have a PxL script that exports OTel data, let's set up the [Plugin System](/reference/plugins/plugin-system/) to run this script at regularly scheduled intervals.
+
+1. Navigate to the `Plugin` tab on the `Admin` page (`/admin/plugins`).
+
+2. Click the toggle to enable the OpenTelemetry plugin.
+
+3. Expand the plugin row (with the arrow next to the toggle) and enter the export path.
+
+> If you are using the demo collector from [Step 1](/tutorials/integrations/otel/#deploy-the-otel-collector), then you'll use the same export path pictured below: `otel-collector.default.svc.cluster.local:4317`
+
+4. Click the toggle to disable "Secure connections with TLS" and press the `SAVE` button. The demo OTel collector does not support TLS.
+
+<svg title='Plugins are enabled in the Admin UI.' src='plugin/plugins_page.png'/>
+
+5. Click the database icon in the left nav bar to open the data export configuration page.
+
+<svg title='Select the data export icon.' src='plugin/data-export-icon.png'/>
+
+6. The OpenTelemetry plugin comes with several pre-configured OTel export PxL scripts (more coming soon!). Click the toggle to disable these scripts for now. For the sake of this tutorial, we want to ensure that the data that the collector receives is actually from our custom script.
+
+<svg title='Disable the pre-configured OpenTelemetry scripts.' src='plugin/data-export.png'/>
+
+7. Select the `+ CREATE SCRIPT` button.
+
+8. Enter `HTTP Throughput` in the `Script Name` field.
+
+9. Replace the contents of the `PxL` field with the following:
+
+```python
+import px
+# Read in the http_events table
+df = px.DataFrame(table='http_events', start_time=px.plugin.start_time)
+
+# Attach the pod and service metadata
+df.pod = df.ctx['pod']
+df.service = df.ctx['service']
+# Count the number of requests per pod and service
+df = df.groupby(['pod', 'service', 'req_path']).agg(
+  throughput=('latency', px.count),
+  time_=('time_', px.max),
+)
+
+# Change the denominator if you change start_time above.
+df.requests_per_s = df.throughput / 10
+
+px.export(df, px.otel.Data(
+  resource={
+      # service.name is required by OpenTelemetry.
+      'service.name' : df.service,
+      'service.instance.id': df.pod,
+      'k8s.pod.name': df.pod,
+  },
+  data=[
+    px.otel.metric.Gauge(
+      name='http.throughput',
+      description='The number of messages sent per second',
+      value=df.requests_per_s,
+      attributes={
+        'req_path': df.req_path,
+      }
+    )
+  ]
+))
+```
+
+> This is the script we developed in [Step 2](/tutorials/integrations/otel/#write-the-pxl-script) with a few modifications:
+
+> - We changed the DataFrame's `start_time` argument to use `px.plugin.start_time`. This value can be configured using the `Summary Window` field on this page.
+
+> - We removed the `Endpoint` parameter. We configured the plugin with this value in Step 3.
+
+> - We removed the `px.display()` call on the last line. This was used to display the data in the Live UI when developing our script in the Scratch Pad.
+
+10. Select the `OpenTelemetry` option from the `Plugin` field drop-down menu.
+
+11. Click the `SAVE` button.
+
+12. To validate that the data is being received by the OTel collector, check logs for the the `otel-collector-*` pod. If the plugin configuration was successful, you should see logs every 10 seconds:
+
+```bash
+2022-04-15T21:17:27.530Z    INFO    loggingexporter/logging_exporter.go:54    MetricsExporter    {"#metrics": 32}
+2022-04-15T21:17:37.570Z    INFO    loggingexporter/logging_exporter.go:54    MetricsExporter    {"#metrics": 30}
+2022-04-15T21:17:47.609Z    INFO    loggingexporter/logging_exporter.go:54    MetricsExporter    {"#metrics": 29}
+2022-04-15T21:17:57.449Z    INFO    loggingexporter/logging_exporter.go:54    MetricsExporter    {"#metrics": 29}
+```
+
+Congrats! You're now exporting Pixie data to an OTel collector.

content/assets/plugin/plugins_page.png

@@ -2,17 +2,18 @@
 title: "Pixie Plugin System"
 metaTitle: "Reference | Plugins | Pixie Plugin System "
 metaDescription: "Pixie's Plugin System"
-order: 1 
+order: 1
 ---
 
-Pixie's primary focus is to build a real-time debugging platform, not a full-fledged observability solution. Pixie provides a plugin system to integrate with external tools to enable capabilities like longterm data retention and alerting.
+Pixie's primary focus is to build a real-time debugging platform, not a full-fledged observability solution. Use the plugin system to integrate with external tools to enable capabilities like longterm data retention and alerting.
 
-- [*Longterm Data Retention*](#longterm-data-retention): Pixie only retains up to 24 hours of data. Leverage an external datastore for longterm data retention by sending Pixie data in the [OpenTelemetry](https://opentelemetry.io/) format. Future support will be added for querying longterm data from within the Pixie UI, allowing you to use PxL and Pixie's versatile live views.
-- *Alerts* (Coming Soon!): Power alerts using Pixie's rich dataset, all configurable from within Pixie's UI.
+- [Longterm Data Retention](#longterm-data-retention): Pixie retains up to 24 hours of data. Leverage an external datastore for longterm data retention by sending Pixie data in the [OpenTelemetry](https://opentelemetry.io/) format. Future support will be added for querying longterm data from within the Pixie UI.
+
+- [Alerts](#alerts) (coming soon): Power alerts using Pixie's rich dataset, all configurable from within the Pixie UI.
 
 ## Enabling a Plugin
 
-Plugins can be configured from within the Admin UI. 
+Plugins can be configured from within the Admin UI.
 
 <svg title='Plugins are accessible through the Admin UI.' src='plugin/plugins_page.png'/>
 
@@ -22,15 +23,17 @@ Plugins can be configured from within the Admin UI.
 
 ## Longterm Data Retention
 
-Enable a plugin which offers longterm data retention capabilities to send Pixie data to an external datastore. This plugin allows you to configure PxL scripts to export data at regularly scheduled intervals. This only currently supports exporting data through the [OpenTelemetry](https://opentelemetry.io/) format. 
+<Alert variant="outlined" severity="info">Check out the <a href="/tutorials/integrations/otel/">tutorial</a> to how to export data in the OTel format.</Alert>
+
+Enable a plugin which offers longterm data retention capabilities to send Pixie data to an external datastore. This plugin allows you to configure PxL scripts to export data at regularly scheduled intervals. This only currently supports exporting data through the [OpenTelemetry](https://opentelemetry.io/) format.
 
 By default, the plugin provider has configured a set of preset scripts. These will automatically start running and exporting data from all clusters in the org as soon as the plugin is enabled. Users can also choose to export custom data by creating a custom export script.
 
 ### Configuring Preset Export Scripts
 
 <svg title='You can view preset scripts for a plugin in the Data Export page.' src='plugin/preset_scripts.png'/>
 
-1. [Enable a plugin provider](#enabling-a-plugin) which supports longterm data retention. 
+1. [Enable a plugin provider](#enabling-a-plugin) which supports longterm data retention.
 2. Open the Live UI and navigate to the Data Export page in the sidebar (`/configure-data-export`).
 3. All preset scripts are listed under `<Plugin Provider> Scripts`.
 4. Click the toggle to enable/disable the export from the preset script.
@@ -41,7 +44,7 @@ By default, the plugin provider has configured a set of preset scripts. These wi
 
 <svg title='Create a custom script in the Data Export page by clicking `Create Scripts`.' src='plugin/custom_scripts.png'/>
 
-1. [Enable a plugin provider](#enabling-a-plugin) which supports longterm data retention. 
+1. [Enable a plugin provider](#enabling-a-plugin) which supports longterm data retention.
 2. Open the Live UI and navigate to the Data Export page in the sidebar (`/configure-data-export`).
 3. Under `Custom Scripts`, click the `Create Scripts` button on the right-hand side.
 4. Enter a script name and description.
@@ -51,7 +54,12 @@ By default, the plugin provider has configured a set of preset scripts. These wi
 8. Select the plugin provider to export this data to.
 9. Click "Create" to save your settings. Data export should start immediately.
 
+## Alerts
+
+Coming soon!
+
 ## Contributing a Plugin
 
-Interested in contributing a plugin to our Plugin system? Check out our [Pixie Plugin Repository](https://github.com/pixie-io/pixie-plugin) and follow the provided instructions.
+Interested in contributing a Pixie plugin?
 
+Check out our [Plugin Repository](https://github.com/pixie-io/pixie-plugin) for more details.