example/metric : Add exponential_histogram README and reorganize fold…

…ers. (#821)

* metric/exponential_histogram : Add README.

* metric/export : Reorganize example/metric folders.

* exponential_histogram: Change dashboard display name.

* example: Remove binaries.

* exponential_histogram: Improve README.

* metric/example :  Revert folder reorg.

* example/metric : Create "dashboards" folder and organize.

* Update copyright date.

* exponential_histogram : Fix conflicting module name

* example/metric : Improve README's.

* exponential_histogram : Fix images path.

* example/metric : Improve README's further.

* sdk : Fix images path.

* example/metric : Small README improvements.

* example/metric : Make build and run instructions example agnostic.

example/metric/README.md

@@ -2,7 +2,7 @@
 
 This example shows how to use [`go.opentelemetry.io/otel`](https://pkg.go.dev/go.opentelemetry.io/otel/) to instrument a simple Go application with metrics and export the metrics to [Google Cloud Monitoring](https://cloud.google.com/monitoring/)
 
-## Build and run the application
+## Setup environment
 
 Before sending metrics to Google Cloud Monitoring, confirm the Cloud Monitoring API is enabled for the project you will use to access the API as described in [this document](https://cloud.google.com/monitoring/api/enable-api).
 
@@ -22,44 +22,38 @@ Next, set this project ID to the environment variable `GOOGLE_PROJECT_ID` using
 export GOOGLE_PROJECT_ID=$(gcloud config get-value project)
 ```
 
-Once you ensure the API is enabled, then build the example application and run the executable. There are two separate examples showcasing the following - 
-1. Exporting metrics via the SDK.
-2. Exporting metrics via the OpenTelemetry Collector.
+### Enable experimental features
+The `exponential_histogram` example can optionally export [exemplars](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#exemplars). Enable experimental [exemplar sampling](https://github.com/open-telemetry/opentelemetry-go/blob/main/sdk/metric/internal/x/README.md#exemplars) support with :
+```
+export OTEL_GO_X_EXEMPLAR=true
+export OTEL_METRICS_EXEMPLAR_FILTER=always_on
+```
 
-Change the current directory to the example you wish to run - either to [sdk](./sdk/) directory or [collector](./collector/) directory and then run the example using following commands:
+## Build and run the application
+
+Once you ensure the API is enabled, then build the example application and run the executable. There are three separate examples showcasing the following - 
+1. Exporting metrics via the SDK - [sdk](./sdk/) directory.
+2. Exporting metrics via the OpenTelemetry Collector - [collector](./collector/).
+3. Exporting histogram metrics via the SDK - [exponential_histogram](./exponential_histogram/).
+
+Change the current directory to the example you wish to run, e.g. `cd sdk` or `cd exponential_histogram`, and then run the example using following commands:
 
 ```
 $ go build -o metrics
 $ ./metrics
-2020/06/11 21:11:15 Most recent data: counter 110, observer 13.45
-2020/06/11 21:11:15 Most recent data: counter 160, observer 16.02
-2020/06/11 21:11:15 Most recent data: counter 134, observer 14.33
-2020/06/11 21:11:15 Most recent data: counter 125, observer 15.12
 ...
 ```
 
-To ensure you have enough data to create interesting charts for the Counter and Observer metrics generated by the example, keep the application running for at least five minutes.
+To ensure you have enough data to create interesting charts for the exported metrics generated by the example, keep the application running for at least five minutes.
 
 *Note: For running the collector example, you need to have a locally running OpenTelemetry Collector, configured using the provided [sample config](./collector/sample-collector-config.yaml). Instructions for running OpenTelemetry Collector on your system can be found [here](https://opentelemetry.io/docs/collector/getting-started/#local).*
 
-## Create dashboard
+## Visualize exported metrics
 
 https://console.cloud.google.com/monitoring/dashboards?project=<your-project-id>
 
 Once you think you have sent sufficient data, then create a dashboard. If you are learning how to use Google Cloud Monitoring, you can follow how to use charts step by step on [this document](https://cloud.google.com/monitoring/charts).
 
-When filling in the **Find resource type and metric box**, use the metric names "custom.googleapis.com/opentelemetry/counter-a" and "custom.googleapis.com/opentelemetry/observer-a".
-
-If you already know how to use Cloud Monitoring and would just like to confirm the data is properly received, you can run the dashboard creation script bundled in this directory.
-
-```
-$ ./create_dashboard.sh
-```
-
-This script creates a dashboard titled "OpenTelemetry exporter example/metric".
-
-You should be able to view line charts like below once you create the dashboard.
-
-*Note: This script is configured to create dashboard which displays the metrics generated via the `sdk` example.*
+When filling in the **Find resource type and metric box**, use the metric names with the prefix "custom.googleapis.com/opentelemetry/counter-a", "custom.googleapis.com/opentelemetry/observer-a" or with prefix "workload.googleapis.com/latency_" (for example "workload.googleapis.com/latency_a").
 
-<img width="1200" alt="2 charts in dashboard" src="images/charts.png?raw=true"/>
+Go to the individual example sub-directories [sdk](./sdk/) or [exponential_histogram](./exponential_histogram/) for further instructions on how to `Create a dashboard` to visualize the exported metrics.

example/metric/exponential_histogram/dashboard.json → example/metric/dashboards/exponential_histogram_dashboard.json

@@ -1,5 +1,5 @@
 {
-    "displayName": "Exponential Histogram",
+    "displayName": "OpenTelemetry - Exponential Histogram example",
     "dashboardFilters": [],
     "mosaicLayout": {
       "columns": 48,

example/metric/exponential_histogram/README.md

@@ -0,0 +1,47 @@
+# Google Cloud Monitoring exponential histogram example
+
+This example shows how to use [`go.opentelemetry.io/otel`](https://pkg.go.dev/go.opentelemetry.io/otel/) to instrument a simple Go application with metrics and export the metrics to [Google Cloud Monitoring](https://cloud.google.com/monitoring/)
+
+## Example details
+
+This example simulates server latency by sampling a [Log-Normal Distribution](https://en.wikipedia.org/wiki/Log-normal_distribution) with the parameters $\mu =  3.5 , 5.5$ and $\sigma = .5$. We generate the following three example of server latency :
+
+1. Latency with Log-Normal Distribution.
+2. Latency with Shifted Mean Distribution.
+3. Latency with Multimodal Distribution (mixture of 1. and 2.).
+
+We explore the resulting distributions with three types of histograms : 
+
+1. Opentelemetry Default Linear Buckets Histogram. Buckets are `0, 5, 10, 25, 50, 75, 100, 250, 500, 1000`
+2. Opentelemetry Linear Buckets Histogram. Buckets are `0, 10, 20, 30, ..., 340, 350`. 
+3. Opentelemetry Exponential Buckets Histogram with default parameters.
+
+## Build and run the application
+
+Go to the [example/metric/README.md](../README.md) instructions that describe how to build and run all examples.
+
+## Sample execution
+
+```
+$ ./metrics
+2024/03/21 15:38:58 Sent Latency Data (Original Distribution): #points 1000 , mean 36.64255895183214, sdv 19.670797833645373
+2024/03/21 15:38:58 Sent Latency Data (Shifted Distribution): #points 1000 , mean 277.70002931783233, sdv 143.59582355437485
+2024/03/21 15:38:58 Sent Latency Data (Multimodal Distribution): #points 1000 , mean 151.49111863163805, sdv 159.2187295223318
+...
+```
+
+## Create dashboard
+
+When filling in the **Find resource type and metric box**, use the metric names with the prefix "workload.googleapis.com/latency_" to observe histogram metrics (for example "workload.googleapis.com/latency_a").
+
+If you already know how to use Cloud Monitoring and would just like to confirm the data is properly received, you can run the dashboard creation script bundled in this directory. This command requires at least the [roles/monitoring.dashboardEditor](https://cloud.google.com/monitoring/access-control#dashboard_roles_desc) permissions to create a new dashboard.
+
+```
+$ ./create_dashboard.sh
+```
+
+This script creates a dashboard titled "OpenTelemetry - Exponential Histogram example".
+
+You should be able to view histogram charts like below once you create the dashboard.
+
+<img width="1200" alt="2 charts in dashboard" src="../images/exponential_histogram_charts.png?raw=true"/>

example/metric/exponential_histogram/create_dashboard.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+# Copyright 2024 Google LLC
+#
+# 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 dashboard is intended to show the metrics emit from the example
+# in the same directory.
+# https://cloud.google.com/monitoring/dashboards/api-dashboard
+gcloud monitoring dashboards create --config-from-file=--config-from-file=../dashboards/exponential_histogram_dashboard.json

example/metric/exponential_histogram/go.mod

@@ -1,4 +1,4 @@
-module github.com/GoogleCloudPlatform/opentelemetry-operations-go/example/metric/sdk
+module github.com/GoogleCloudPlatform/opentelemetry-operations-go/example/metric/exponential_histogram
 
 go 1.20
 

example/metric/sdk/README.md

@@ -0,0 +1,35 @@
+# Google Cloud Monitoring exporter example
+
+This example shows how to use [`go.opentelemetry.io/otel`](https://pkg.go.dev/go.opentelemetry.io/otel/) to instrument a simple Go application with metrics and export the metrics to [Google Cloud Monitoring](https://cloud.google.com/monitoring/)
+
+## Build and run the application
+
+Go to the [example/metric/README.md](../README.md) instructions that describe how to build and run all examples.
+
+## Sample execution
+
+```
+$ ./metrics
+2020/06/11 21:11:15 Most recent data: counter 110, observer 13.45
+2020/06/11 21:11:15 Most recent data: counter 160, observer 16.02
+2020/06/11 21:11:15 Most recent data: counter 134, observer 14.33
+2020/06/11 21:11:15 Most recent data: counter 125, observer 15.12
+...
+```
+
+## Create dashboard
+
+When filling in the **Find resource type and metric box**, use the metric names "custom.googleapis.com/opentelemetry/counter-a" and "custom.googleapis.com/opentelemetry/observer-a".
+
+If you already know how to use Cloud Monitoring and would just like to confirm the data is properly received, you can run the dashboard creation script bundled in this directory. This command requires at least the [roles/monitoring.dashboardEditor](https://cloud.google.com/monitoring/access-control#dashboard_roles_desc) permissions to create a new dashboard.
+```
+$ ./create_dashboard.sh
+```
+
+This script creates a dashboard titled "OpenTelemetry exporter example/metric".
+
+You should be able to view line charts like below once you create the dashboard.
+
+*Note: This script is configured to create dashboard which displays the metrics generated via the `sdk` example.*
+
+<img width="1200" alt="2 charts in dashboard" src="../images/sdk_charts.png?raw=true"/>

example/metric/create_dashboard.sh → example/metric/sdk/create_dashboard.sh

@@ -17,4 +17,4 @@
 # This dashboard is intended to show the metrics emit from the example
 # in the same directory.
 # https://cloud.google.com/monitoring/dashboards/api-dashboard
-gcloud monitoring dashboards create --config-from-file=dashboard.json
+gcloud monitoring dashboards create --config-from-file=../dashboards/sdk_dashboard.json