Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README.md #1106

Merged
merged 3 commits into from
Aug 27, 2020
Merged

Update README.md #1106

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
933c14f
Update README.md
MrAlias Aug 27, 2020
e12e734
Fix spelling error
MrAlias Aug 27, 2020
ae95a80
Apply suggestions from code review
MrAlias Aug 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 37 additions & 60 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 provides a single set of APIs to capture distributed
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
traces and metrics from your application and send them to an observability
platform. This project allows you to do just that for application written in
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
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).