Update README.md (#1106)

* Update README.md Replace `Installation` and `Compatible Libraries` sections with a more comprehensive `Getting Started` section to address the two actions most users will want to know about: instrumenting and exporting. Remove the code example. Add links to project boards and milestones to address project status questions. * Fix spelling error * Apply suggestions from code review Co-authored-by: ET <[email protected]> Co-authored-by: ET <[email protected]>
open-telemetry · Aug 27, 2020 · 06a0be7 · 06a0be7
1 parent 3b3c263
commit 06a0be7
Showing 1 changed file with 37 additions and 60 deletions.
diff --git a/README.md b/README.md
@@ -5,76 +5,53 @@
 [![Go Report Card](https://goreportcard.com/badge/go.opentelemetry.io/otel)](https://goreportcard.com/report/go.opentelemetry.io/otel)
 [![Gitter](https://badges.gitter.im/open-telemetry/opentelemetry-go.svg)](https://gitter.im/open-telemetry/opentelemetry-go?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
-The Go [OpenTelemetry](https://opentelemetry.io/) client.
+The Go [OpenTelemetry](https://opentelemetry.io/) implementation.
 
-## Installation
+## Getting Started
 
-This repository includes multiple packages. The `api`
-package contains core data types, interfaces and no-op implementations that comprise the OpenTelemetry API following
-[the
-specification](https://github.com/open-telemetry/opentelemetry-specification).
-The `sdk` package is the reference implementation of the API.
+OpenTelemetry's goal is to provide a single set of APIs to capture distributed
+traces and metrics from your application and send them to an observability
+platform. This project allows you to do just that for applications written in
+Go. There are two steps to this process: instrument your application, and
+configure an exporter.
 
-Libraries that produce telemetry data should only depend on `api`
-and defer the choice of the SDK to the application developer. Applications may
-depend on `sdk` or another package that implements the API.
+### Instrumentation
 
-All packages are published to [go.opentelemetry.io/otel](https://pkg.go.dev/go.opentelemetry.io/otel) and is the preferred location to import from.
+To start capturing distributed traces and metric events from your application
+it first needs to be instrumented. The easiest way to do this is by using an
+instrumentation library for your code. Be sure to check out [the officially
+supported instrumentation
+libraries](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/master/instrumentation).
 
-Additional resources:
+If you need to extend the telemetry an instrumentation library provides or want
+to build your own instrumentation for your application directly you will need
+to use the
+[go.opentelemetry.io/otel/api](https://pkg.go.dev/go.opentelemetry.io/otel/api)
+package. The included [examples](./example/) are a good way to see some
+practical uses of this process.
 
-- [Developing using Go Modules](https://blog.golang.org/using-go-modules)
-- [Adding dependencies and installing them](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)
+### Export
 
-## Quick Start
+Now that your application is instrumented to collect telemetry, it needs an
+export pipeline to send that telemetry to an observability platform.
 
-Below is a brief example of importing OpenTelemetry, initializing a tracer and creating some simple spans.
+You can find officially supported exporters [here](./exporters/) and in the
+companion [contrib
+repository](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/master/exporters/metric).
+Additionally, there are many vendor specific or 3rd party exporters for
+OpenTelemetry. These exporters are broken down by
+[trace](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/export/trace?tab=importedby)
+and
+[metric](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/export/metric?tab=importedby)
+support.
 
-```go
-package main
+## Project Status
 
-import (
-	"context"
-	"log"
-
-	"go.opentelemetry.io/otel/api/global"
-	"go.opentelemetry.io/otel/exporters/stdout"
-	sdktrace "go.opentelemetry.io/otel/sdk/trace"
-)
-
-func main() {
-	pusher, err := stdout.InstallNewPipeline(nil, nil)
-	if err != nil {
-		log.Fatal(err)
-	}
-	defer pusher.Stop()
-
-	tracer := global.Tracer("ex.com/basic")
-	ctx, span := tracer.Start(context.Background(), "main")
-	defer span.End()
-	/* … */
-}
-```
-
-See the [API
-documentation](https://pkg.go.dev/go.opentelemetry.io/otel) for more
-detail, and the
-[opentelemetry examples](./example/).
-
-## Compatible Exporters
-
-See the Go packages depending upon
-[sdk/export/trace](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/export/trace?tab=importedby)
-and [sdk/export/metric](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/export/metric?tab=importedby)
-for a list of all exporters compatible with OpenTelemetry's Go SDK.
-
-## Compatible Libraries
-
-See the
-[opentelemetry-go-contrib](https://github.com/open-telemetry/opentelemetry-go-contrib)
-repo for packages that facilitates instrumenting other useful Go libraries
-with opentelemetry-go for distributed tracing and monitoring.
+[Project boards](https://github.com/open-telemetry/opentelemetry-go/projects)
+and [milestones](https://github.com/open-telemetry/opentelemetry-go/milestones)
+can be found at the respective links. We try to keep these accurate and should
+be the best place to go for answers on project status.
 
 ## Contributing
 
-See the [contributing file](CONTRIBUTING.md).
+See the [contributing documentation](CONTRIBUTING.md).