<commit_before># OpenTelemetry Service

*IMPORTANT:* This is a pre-released version of the OpenTelemetry Service.
For now, please use the [OpenCensus Service](https://github.com/census-instrumentation/opencensus-service).

[![Build Status][travis-image]][travis-url]
[![GoDoc][godoc-image]][godoc-url]
[![Gitter chat][gitter-image]][gitter-url]
[![Coverage Status][codecov-image]][codecov-url]

# Table of contents
- [Introduction](#introduction)
- [Deployment](#deploy)
- [Getting Started](#getting-started)
    - [Demo](#getting-started-demo)
    - [Kubernetes](#getting-started-k8s)
    - [Standalone](#getting-started-standalone)
- [Configuration](#config)
    - [Receivers](#config-receivers)
    - [Exporters](#config-exporters)
    - [Diagnostics](#config-diagnostics)
    - [Global Attributes](#global-attributes)
    - [Sampling](#sampling)
- [Usage](#usage)

## Introduction

The OpenTelemetry Service can collect traces and metrics from processes
instrumented by OpenTelemetry or other monitoring/tracing libraries (Jaeger,
Prometheus, etc.), handles aggregation and smart sampling, and export traces
and metrics to one or more monitoring/tracing backends.

Some frameworks and ecosystems are now providing out-of-the-box instrumentation
by using OpenTelemetry, but the user is still expected to register an exporter
in order to export data. This is a problem during an incident. Even though our
users can benefit from having more diagnostics data coming out of services
already instrumented with OpenTelemetry, they have to modify their code to
register an exporter and redeploy. Asking our users recompile and redeploy is
not an ideal at an incident time. In addition, currently users need to decide
which service backend they want to export to, before they distribute their
binary instrumented by OpenTelemetry.

The OpenTelemetry Service is trying to eliminate these requirements. With the
OpenTelemetry Service, users do not need to redeploy or restart their
applications as long as it has the OpenTelemetry exporter. All they need to do
is just configure and deploy the OpenTelemetry Service separately. The
OpenTelemetry Service will then automatically collect traces and metrics and
export to any backend of users' choice.

Currently the OpenTelemetry Service consists of a single binary and two
deployment methods:

1. [Agent](#opentelemetry-agent) running with the application or on the same host as the application
2. [Collector](#opentelemetry-collector) running as a standalone application

For the detailed design specs, please see [DESIGN.md](DESIGN.md).

## <a name="deploy"></a>Deployment

The OpenTelemetry Service can be deployed in a variety of different ways
depending on requirements. The Agent can be deployed with the application
either as a separate process, as a sidecar, or via a Kubernetes daemonset. The
Collector is deployed as a separate application as either a Docker container,
VM, or Kubernetes pod.

While the Agent and Collector share the same binary, the configuration between
the two may differ depending on requirements (e.g. queue size and feature-set
enabled).

![deployment-models](https://i.imgur.com/Tj384ap.png)

## <a name="getting-started"></a>Getting Started

### <a name="getting-started-demo"></a>Demo

Instructions for setting up an end-to-end demo environment can be found [here](https://github.com/open-telemetry/opentelemetry-service/tree/master/demos/trace)

### <a name="getting-started-k8s"></a>Kubernetes

Apply the [sample YAML](example/k8s.yaml) file:

```shell
$ kubectl apply -f example/k8s.yaml
```

### <a name="getting-started-standalone"></a>Standalone

Create an Agent [configuration](#config) file based on the options described
below. By default, the Agent has the `opencensus` receiver enabled, but no
exporters configured.

Build the Agent, see [Usage](##agent-usage),
and start it:

```shell
$ ./bin/otelsvc_$(go env GOOS)
$ 2018/10/08 21:38:00 Running OpenTelemetry receiver as a gRPC service at "127.0.0.1:55678"
```

Create an Collector [configuration](#config) file based on the options
described below. By default, the Collector has the `opencensus` receiver
enabled, but no exporters configured.

Build the Collector and start it:

```shell
$ make otelsvc
$ ./bin/otelsvc_$($GOOS)
```

Run the demo application:

```shell
$ go run "$(go env GOPATH)/src/github.com/open-telemetry/opentelemetry-service/example/main.go"
```

You should be able to see the traces in your exporter(s) of choice. If you stop
the ocagent, the example application will stop exporting. If you run it again,
exporting will resume.

## <a name="config"></a>Configuration

The OpenTelemetry Service (both the Agent and Collector) is configured via a
YAML file. In general, you need to configure one or more receivers as well as
one or more exporters. In addition, diagnostics can also be configured.

### <a name="config-receivers"></a>Receivers
<commit_msg>Fix links to demotrace and examples (#114)<commit_after># OpenTelemetry Service

*IMPORTANT:* This is a pre-released version of the OpenTelemetry Service.
For now, please use the [OpenCensus Service](https://github.com/census-instrumentation/opencensus-service).

[![Build Status][travis-image]][travis-url]
[![GoDoc][godoc-image]][godoc-url]
[![Gitter chat][gitter-image]][gitter-url]
[![Coverage Status][codecov-image]][codecov-url]

# Table of contents
- [Introduction](#introduction)
- [Deployment](#deploy)
- [Getting Started](#getting-started)
    - [Demo](#getting-started-demo)
    - [Kubernetes](#getting-started-k8s)
    - [Standalone](#getting-started-standalone)
- [Configuration](#config)
    - [Receivers](#config-receivers)
    - [Exporters](#config-exporters)
    - [Diagnostics](#config-diagnostics)
    - [Global Attributes](#global-attributes)
    - [Sampling](#sampling)
- [Usage](#usage)

## Introduction

The OpenTelemetry Service can collect traces and metrics from processes
instrumented by OpenTelemetry or other monitoring/tracing libraries (Jaeger,
Prometheus, etc.), handles aggregation and smart sampling, and export traces
and metrics to one or more monitoring/tracing backends.

Some frameworks and ecosystems are now providing out-of-the-box instrumentation
by using OpenTelemetry, but the user is still expected to register an exporter
in order to export data. This is a problem during an incident. Even though our
users can benefit from having more diagnostics data coming out of services
already instrumented with OpenTelemetry, they have to modify their code to
register an exporter and redeploy. Asking our users recompile and redeploy is
not an ideal at an incident time. In addition, currently users need to decide
which service backend they want to export to, before they distribute their
binary instrumented by OpenTelemetry.

The OpenTelemetry Service is trying to eliminate these requirements. With the
OpenTelemetry Service, users do not need to redeploy or restart their
applications as long as it has the OpenTelemetry exporter. All they need to do
is just configure and deploy the OpenTelemetry Service separately. The
OpenTelemetry Service will then automatically collect traces and metrics and
export to any backend of users' choice.

Currently the OpenTelemetry Service consists of a single binary and two
deployment methods:

1. [Agent](#opentelemetry-agent) running with the application or on the same host as the application
2. [Collector](#opentelemetry-collector) running as a standalone application

For the detailed design specs, please see [DESIGN.md](DESIGN.md).

## <a name="deploy"></a>Deployment

The OpenTelemetry Service can be deployed in a variety of different ways
depending on requirements. The Agent can be deployed with the application
either as a separate process, as a sidecar, or via a Kubernetes daemonset. The
Collector is deployed as a separate application as either a Docker container,
VM, or Kubernetes pod.

While the Agent and Collector share the same binary, the configuration between
the two may differ depending on requirements (e.g. queue size and feature-set
enabled).

![deployment-models](https://i.imgur.com/Tj384ap.png)

## <a name="getting-started"></a>Getting Started

### <a name="getting-started-demo"></a>Demo

Instructions for setting up an end-to-end demo environment can be found [here](https://github.com/open-telemetry/opentelemetry-service/tree/master/examples/demotrace)

### <a name="getting-started-k8s"></a>Kubernetes

Apply the [sample YAML](example/k8s.yaml) file:

```shell
$ kubectl apply -f example/k8s.yaml
```

### <a name="getting-started-standalone"></a>Standalone

Create an Agent [configuration](#config) file based on the options described
below. By default, the Agent has the `opencensus` receiver enabled, but no
exporters configured.

Build the Agent, see [Usage](##agent-usage),
and start it:

```shell
$ ./bin/otelsvc_$(go env GOOS)
$ 2018/10/08 21:38:00 Running OpenTelemetry receiver as a gRPC service at "127.0.0.1:55678"
```

Create an Collector [configuration](#config) file based on the options
described below. By default, the Collector has the `opencensus` receiver
enabled, but no exporters configured.

Build the Collector and start it:

```shell
$ make otelsvc
$ ./bin/otelsvc_$($GOOS)
```

Run the demo application:

```shell
$ go run "$(go env GOPATH)/src/github.com/open-telemetry/opentelemetry-service/examples/main.go"
```

You should be able to see the traces in your exporter(s) of choice. If you stop
the ocagent, the example application will stop exporting. If you run it again,
exporting will resume.

## <a name="config"></a>Configuration

The OpenTelemetry Service (both the Agent and Collector) is configured via a
YAML file. In general, you need to configure one or more receivers as well as
one or more exporters. In addition, diagnostics can also be configured.

### <a name="config-receivers"></a>Receivers

{'fraction_non_alphanumeric': 0.0940759493670886, 'fraction_numerical': 0.007189873417721519, 'mean_word_length': 5.092535471930907, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 31, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2287548', 'n_tokens_mistral': 2903, 'n_tokens_neox': 2712, 'n_words': 1138}