Add README to trace and metric exporter (#44)

* Fixes #21
* Fixes #22
* Change all go.mod to use Go 1.14

README.md

@@ -1,6 +1,15 @@
 # Open-Telemetry Operations Exporters for Go
 
-Provides OpenTelemetry Exporters for Google Cloud Operations. 
+This repository contains the source code of 2 packages of OpenTelemetry exporters to [Google Cloud Trace](https://cloud.google.com/trace) and [Google Cloud Monitoring](https://cloud.google.com/monitoring).
 
-## Installation
+## OpenTelemetry Google Cloud Trace Exporter
 
+OpenTelemetry Google Cloud Trace Exporter allow the user to send collected traces and spans to Google Cloud.
+
+See [README.md](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/blob/master/exporter/trace/README.go) for setup and usage information.
+
+## OpenTelemetry Google Cloud Monitoring Exporter
+
+OpenTelemetry Google Cloud Monitoring Exporter allows the user to send collected metrics to Google Cloud Monitoring.
+
+See [README.md](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/blob/master/exporter/metrics/README.go) for setup and usage information.

exporter/metric/README.md

@@ -0,0 +1,66 @@
+# OpenTelemetry Google Cloud Monitoring Exporter
+
+[![Docs](https://godoc.org/github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric?status.svg)](https://pkg.go.dev/github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric)
+[![Apache License][license-image]][license-url]
+
+OpenTelemetry Google Cloud Monitoring Exporter allow the user to send collected metrics to Google Cloud.
+
+[Google Cloud Monitoring](https://cloud.google.com/monitoring) provides visibility into the performance, uptime, and overall health of cloud-powered applications. It collects metrics, events, and metadata from Google Cloud, Amazon Web Services, hosted uptime probes, application instrumentation, and a variety of common application components including Cassandra, Nginx, Apache Web Server, Elasticsearch, and many others. Operations ingests that data and generates insights via dashboards, charts, and alerts. Cloud Monitoring alerting helps you collaborate by integrating with Slack, PagerDuty, and more.
+
+## Setup
+
+Google Cloud Monitoring is a managed service provided by Google Cloud Platform. Google Cloud Monitoring requires to set up "Workspace" in advance. The guide to create a new Workspace is available on [the official document](https://cloud.google.com/monitoring/workspaces/create).
+
+## Usage
+
+Add `github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric` to the import list and set up `go.mod` file accordingly.
+
+```go
+import mexpoter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric"
+```
+
+After you import the metric exporter package, then register the exporter to the application, and start sending metrics. If you are running in a GCP environment, the exporter will automatically authenticate using the environment's service account. If not, you will need to follow the instructions in [Authentication](#Authentication).
+
+```go
+
+import (
+    ... (omitted)
+    "go.opentelemetry.io/otel/api/metric"
+)
+
+// Initialize exporter option.
+opts := []mexporter.Option{}
+
+// Create exporter (collector embedded with the exporter).
+pusher, err := mexporter.InstallNewPipeline(opts, nil)
+if err != nil {
+    log.Fatalf("mexporter.InstallNewPipeline: %v", err)
+}
+defer pusher.Stop()
+
+// Start meter
+ctx := context.Background()
+meter := pusher.Provider().Meter("cloudmonitoring/example")
+
+counter := metric.Must(meter).NewInt64Counter("counter-foo")
+labels := []kv.KeyValue{kv.Key("key").String("value")}
+counter.Add(ctx, 123, labels...)
+```
+
+Note that, as of version 0.2.1, `ValueObserver` and `ValueRecorder` are aggregated to `LastValue`, and other metric kinds are to `Sum`. This behaviour should be change once [Views API](https://github.com/open-telemetry/oteps/pull/89) is introduced to the specification.
+
+## Authentication
+
+The Google Cloud Trace exporter depends upon [`google.FindDefaultCredentials`](https://pkg.go.dev/golang.org/x/oauth2/google?tab=doc#FindDefaultCredentials), so the service account is automatically detected by default, but also the custom credential file (so called `service_account_key.json`) can be detected with specific conditions. Quoting from the document of `google.FindDefaultCredentials`:
+
+* A JSON file whose path is specified by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
+* A JSON file in a location known to the gcloud command-line tool. On Windows, this is `%APPDATA%/gcloud/application_default_credentials.json`. On other systems, `$HOME/.config/gcloud/application_default_credentials.json`.
+
+## Useful links
+
+* For more information on OpenTelemetry, visit: https://opentelemetry.io/
+* For more about OpenTelemetry Go, visit: https://github.com/open-telemetry/opentelemetry-go
+* Learn more about Google Cloud Monitoring at https://cloud.google.com/monitoring
+
+[license-url]: https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/blob/master/LICENSE
+[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat

exporter/trace/README.md

@@ -0,0 +1,70 @@
+# OpenTelemetry Google Cloud Trace Exporter
+
+[![Docs](https://godoc.org/github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace?status.svg)](https://pkg.go.dev/github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace)
+[![Apache License][license-image]][license-url]
+
+OpenTelemetry Google Cloud Trace Exporter allow the user to send collected traces and spans to Google Cloud.
+
+[Google Cloud Trace](https://cloud.google.com/trace) is a distributed tracing backend system. It helps developers to gather timing data needed to troubleshoot latency problems in microservice & monolithic architectures. It manages both the collection and lookup of gathered trace data.
+
+This exporter package assumes your application is [already instrumented](https://github.com/open-telemetry/opentelemetry-go/blob/master/example/http/client/client.go) with the OpenTelemetry SDK. Once you get ready to export OpenTelemetry data, you can add this exporter to your application.
+
+## Setup
+
+Google Cloud Trace is a managed service provided by Google Cloud Platform. The end-to-end set up guide with OpenTelemetry is available on [the office document](https://cloud.google.com/trace/docs/setup/go-ot), so this document go through the exporter set up.
+
+## Usage
+
+Add `github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace` to the import list and set up `go.mod` file accordingly.
+
+```go
+import texpoter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
+```
+
+Once you import the trace exporter package, then register the exporter to the application, and start tracing. If you are running in a GCP environment, the exporter will automatically authenticate using the environment's service account. If not, you will need to follow the instruction in [Authentication](#Authentication).
+
+```go
+// Create exporter.
+projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
+exporter, err := texporter.NewExporter(texporter.WithProjectID(projectID))
+if err != nil {
+    log.Fatalf("texporter.NewExporter: %v", err)
+}
+// Create trace provider with the exporter.
+//
+// By default it uses AlwaysSample() which samples all traces.
+// In a production environment or high QPS setup please use
+// ProbabilitySampler set at the desired probability.
+// Example:
+//   config := sdktrace.Config{DefaultSampler:sdktrace.ProbabilitySampler(0.0001)}
+//   tp, err := sdktrace.NewProvider(sdktrace.WithConfig(config), ...)
+tp, err := sdktrace.NewProvider(sdktrace.WithSyncer(exporter))
+if err != nil {
+        log.Fatal(err)
+}
+global.SetTraceProvider(tp)
+
+// Create custom span.
+tracer := global.TraceProvider().Tracer("example.com/trace")
+tracer.WithSpan(context.Background(), "foo",
+        func(_ context.Context) error {
+                // Do some work.
+                return nil
+        })
+```
+
+## Authentication
+
+The Google Cloud Trace exporter depends upon [`google.FindDefaultCredentials`](https://pkg.go.dev/golang.org/x/oauth2/google?tab=doc#FindDefaultCredentials), so the service account is automatically detected by default, but also the custom credential file (so called `service_account_key.json`) can be detected with specific conditions. Quoting from the document of `google.FindDefaultCredentials`:
+
+* A JSON file whose path is specified by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
+* A JSON file in a location known to the gcloud command-line tool. On Windows, this is `%APPDATA%/gcloud/application_default_credentials.json`. On other systems, `$HOME/.config/gcloud/application_default_credentials.json`.
+
+## Useful links
+
+* For more information on OpenTelemetry, visit: https://opentelemetry.io/
+* For more about OpenTelemetry Go, visit: https://github.com/open-telemetry/opentelemetry-go
+* Learn more about Google Cloud Trace at https://cloud.google.com/trace
+
+[license-url]: https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/blob/master/LICENSE
+[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat

exporter/trace/go.mod

@@ -1,6 +1,6 @@
 module github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace
 
-go 1.13
+go 1.14
 
 require (
 	cloud.google.com/go v0.53.0

go.mod

@@ -1,3 +1,3 @@
 module github.com/GoogleCloudPlatform/opentelemetry-operations-go
 
-go 1.13
+go 1.14