Update initial docs to OpenTelemetry (#19)

This is the highest priority as part of the migration. Future PRs will
handle the complete rename.

Author: flands

.travis.yml

@@ -1,6 +1,6 @@
 language: go
 
-go_import_path: github.com/census-instrumentation/opencensus-service
+go_import_path: github.com/open-telemetry/opentelemetry-service
 
 go:
   - 1.12.x

CONTRIBUTING.md

@@ -1,27 +1,52 @@
-# How to contribute
+# Contributing Guide
 
-We'd love to accept your patches and contributions to this project. There are
-just a few small guidelines you need to follow.
+We'd love your help!
 
-## Contributor License Agreement
+## Report a bug or requesting feature
 
-Contributions to this project must be accompanied by a Contributor License
-Agreement. You (or your employer) retain the copyright to your contribution,
-this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
-your current agreements on file or to sign a new one.
+Reporting bugs is an important contribution. Please make sure to include:
 
-You generally only need to submit a CLA once, so if you've already submitted one
-(even if it was for a different project), you probably don't need to do it
-again.
+* Expected and actual behavior
+* OpenTelemetry version you are running
+* If possible, steps to reproduce
 
-## Code reviews
+## How to contribute
 
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult [GitHub Help] for more
-information on using pull requests.
+### Before you start
 
-[GitHub Help]: https://help.github.com/articles/about-pull-requests/
+Please read project contribution
+[guide](https://github.com/open-telemetry/community/blob/master/CONTRIBUTING.md)
+for general practices for OpenTelemetry project.
+
+### Fork
+
+In the interest of keeping this repository clean and manageable, you should
+work from a fork. To create a fork, click the 'Fork' button at the top of the
+repository, then clone the fork locally using `git clone
+[email protected]:USERNAME/opentelemetry-service.git`.
+
+You should also add this repository as an "upstream" repo to your local copy,
+in order to keep it up to date. You can add this as a remote like so:
+
+`git remote add upstream https://github.com/open-telemetry/opentelemetry-service.git
+
+# verify that the upstream exists
+git remote -v`
+
+To update your fork, fetch the upstream repo's branches and commits, then merge your master with upstream's master:
+
+```
+git fetch upstream
+git checkout master
+git merge upstream/master
+```
+
+Remember to always work in a branch of your local copy, as you might otherwise
+have to contend with conflicts in master.
+
+Please also see [GitHub
+workflow](https://github.com/open-telemetry/community/blob/master/CONTRIBUTING.md#github-workflow)
+section of general project contributing guide.
 
 ## Required Tools
 
@@ -38,14 +63,14 @@ Working with the project sources requires the following tools:
 Fork the repo, checkout the upstream repo to your GOPATH by:
 
 ```
-$ GO111MODULE="" go get -d github.com/census-instrumentation/opencensus-service
+$ GO111MODULE="" go get -d github.com/open-telemetry/opentelemetry-service
 ```
 
 Add your fork as an origin:
 
 ```shell
-$ cd $(go env GOPATH)/src/github.com/census-instrumentation/opencensus-service
-$ git remote add fork [email protected]:YOUR_GITHUB_USERNAME/opencensus-service.git
+$ cd $(go env GOPATH)/src/github.com/open-telemetry/opentelemetry-service
+$ git remote add fork [email protected]:YOUR_GITHUB_USERNAME/opentelemetry-service.git
 ```
 
 Run tests, fmt and lint:
@@ -78,4 +103,4 @@ Travis CI uses the Makefile with the default target, it is recommended to
 run it before submitting your PR. It runs `gofmt -s` (simplify) and `golint`.
 
 The dependencies are managed with `go mod` if you work with the sources under your
-`$GOPATH` you need to set the environment variable `GO111MODULE=on`.
+`$GOPATH` you need to set the environment variable `GO111MODULE=on`.

DESIGN.md

@@ -1,19 +1,19 @@
-# OpenCensus Service Design Specs
+# OpenTelemetry Service Design Specs
 
-This document describes the architecture design and implementation of OpenCensus Agent and
-OpenCensus Collector.
+This document describes the architecture design and implementation of OpenTelemetry Agent and
+OpenTelemetry Collector.
 
 # Table of contents
 - [Goals](#goals)
-- [OpenCensus Agent](#opencensus-agent)
+- [OpenTelemetry Agent](#opentelemetry-agent)
     - [Architecture overview](#agent-architecture-overview)
     - [Communication](#agent-communication)
     - [Protocol Workflow](#agent-protocol-workflow)
     - [Implementation details of Agent server](#agent-implementation-details-of-agent-server)
         - [Receivers](#agent-impl-receivers)
         - [Agent Core](#agent-impl-agent-core)
         - [Exporters](#agent-impl-exporters)
-- [OpenCensus Collector](#opencensus-collector)
+- [OpenTelemetry Collector](#opentelemetry-collector)
     - [Architecture overview](#collector-architecture-overview)
 
 ## <a name="goals"></a>Goals
@@ -23,32 +23,32 @@ optionally run a daemon on the host and it will read the
 collected data and upload to the configured backend.
 * Binaries can be instrumented without thinking about the exporting story.
 Allows open source binary projects (e.g. web servers like Caddy or Istio Mixer)
-to adopt OpenCensus without having to link any exporters into their binary.
+to adopt OpenTelemetry without having to link any exporters into their binary.
 * Easier to scale the exporter development. Not every language has to
 implement support for each backend.
 * Custom daemons containing only the required exporters compiled in can be created.
 
-## <a name="opencensus-agent"></a>OpenCensus Agent
+## <a name="opentelemetry-agent"></a>OpenTelemetry Agent
 
 ### <a name="agent-architecture-overview"></a>Architecture Overview
 
 On a typical VM/container, there are user applications running in some processes/pods with
-OpenCensus Library (Library). Previously, Library did all the recording, collecting, sampling and
+OpenTelemetry Library (Library). Previously, Library did all the recording, collecting, sampling and
 aggregation on spans/stats/metrics, and exported them to other persistent storage backends via the
 Library exporters, or displayed them on local zpages. This pattern has several drawbacks, for
 example:
 
-1. For each OpenCensus Library, exporters/zpages need to be re-implemented in native languages.
+1. For each OpenTelemetry Library, exporters/zpages need to be re-implemented in native languages.
 2. In some programming languages (e.g Ruby, PHP), it is difficult to do the stats aggregation in
 process.
-3. To enable exporting OpenCensus spans/stats/metrics, application users need to manually add
+3. To enable exporting OpenTelemetry spans/stats/metrics, application users need to manually add
 library exporters and redeploy their binaries. This is especially difficult when there’s already
-an incident and users want to use OpenCensus to investigate what’s going on right away.
+an incident and users want to use OpenTelemetry to investigate what’s going on right away.
 4. Application users need to take the responsibility in configuring and initializing exporters.
 This is error-prone (e.g they may not set up the correct credentials\monitored resources), and
-users may be reluctant to “pollute” their code with OpenCensus.
+users may be reluctant to “pollute” their code with OpenTelemetry.
 
-To resolve the issues above, we are introducing OpenCensus Agent (Agent). Agent runs as a daemon
+To resolve the issues above, we are introducing OpenTelemetry Agent (Agent). Agent runs as a daemon
 in the VM/container and can be deployed independent of Library. Once Agent is deployed and
 running, it should be able to retrieve spans/stats/metrics from Library, export them to other
 backends. We MAY also give Agent the ability to push configurations (e.g sampling probability) to
@@ -84,7 +84,7 @@ assoicated, Agent should handle the data properly, as if they were sent in a sub
 Identifier is no longer needed once the streams are established.
 3. On Library side, if connection to Agent failed, Library should retry indefintely if possible,
 subject to available/configured memory buffer size. (Reason: consider environments where the
-running applications are already instrumented with OpenCensus Library but Agent is not deployed
+running applications are already instrumented with OpenTelemetry Library but Agent is not deployed
 yet. Sometime in the future, we can simply roll out the Agent to those environments and Library
 would automatically connect to Agent with indefinite retries. Zero changes are required to the
 applications.) Depending on the language and implementation, retry can be done in either
@@ -105,7 +105,7 @@ invocations.
 
 The Agent consists of three main parts:
 
-1. The receivers of different instrumentation libraries, such as OpenCensus, Zipkin,
+1. The receivers of different instrumentation libraries, such as OpenTelemetry, Zipkin,
 Istio Mixer, Prometheus client, etc. Receivers act as the “frontend” or “gateway” of
 Agent. In addition, there MAY be one special receiver for receiving configuration updates
 from outside.
@@ -149,18 +149,18 @@ Once in a while, Agent Core will push `SpanProto` with `Node` to each exporter.
 receiving them, each exporter will translate `SpanProto` to the format supported by the
 backend (e.g Jaeger Thrift Span), and then push them to corresponding backend or service.
 
-## <a name="opencensus-collector"></a>OpenCensus Collector
+## <a name="opentelemetry-collector"></a>OpenTelemetry Collector
 
 ### <a name="collector-architecture-overview"></a>Architecture Overview
 
-The OpenCensus Collector runs as a standalone instance and receives spans and
-metrics exporterd by one or more OpenCensus Agents or Libraries, or by
+The OpenTelemetry Collector runs as a standalone instance and receives spans and
+metrics exporterd by one or more OpenTelemetry Agents or Libraries, or by
 tasks/agents that emit in one of the supported protocols. The Collector is
 configured to send data to the configured exporter(s). The following figure
 summarizes the deployment architecture:
 
-![OpenCensus Collector Architecture](https://user-images.githubusercontent.com/10536136/46637070-65f05f80-cb0f-11e8-96e6-bc56468486b3.png "OpenCensus Collector Architecture")
+![OpenTelemetry Collector Architecture](https://user-images.githubusercontent.com/10536136/46637070-65f05f80-cb0f-11e8-96e6-bc56468486b3.png "OpenTelemetry Collector Architecture")
 
-The OpenCensus Collector can also be deployed in other configurations, such as
+The OpenTelemetry Collector can also be deployed in other configurations, such as
 receiving data from other agents or clients in one of the formats supported by
 its receivers.

Makefile

@@ -16,7 +16,7 @@ GOVET=go vet
 GOOS=$(shell go env GOOS)
 
 GIT_SHA=$(shell git rev-parse --short HEAD)
-BUILD_INFO_IMPORT_PATH=github.com/census-instrumentation/opencensus-service/internal/version
+BUILD_INFO_IMPORT_PATH=github.com/open-telemetry/opentelemetry-service/internal/version
 BUILD_X1=-X $(BUILD_INFO_IMPORT_PATH).GitHash=$(GIT_SHA)
 ifdef VERSION
 BUILD_X2=-X $(BUILD_INFO_IMPORT_PATH).Version=$(VERSION)
@@ -44,7 +44,7 @@ travis-ci: fmt vet lint test-with-cover
 .PHONY: test-with-cover
 test-with-cover:
 	@echo Verifying that all packages have test files to count in coverage
-	@scripts/check-test-files.sh $(subst github.com/census-instrumentation/opencensus-service/,./,$(ALL_PKGS))
+	@scripts/check-test-files.sh $(subst github.com/open-telemetry/opentelemetry-service/,./,$(ALL_PKGS))
 	@echo pre-compiling tests
 	@time go test -i $(ALL_PKGS)
 	$(GOTEST) $(GOTEST_OPT_WITH_COVERAGE) $(ALL_PKGS)

PERFORMANCE.MD

@@ -1,18 +1,18 @@
-# OpenCensus Service Performance
+# OpenTelemetry Service Performance
 
 The performance numbers that follow were generated using version 0.1.3 of the
-OpenCensus Service, are applicable primarily to the OpenCensus Collector and
+OpenTelemetry Service, are applicable primarily to the OpenTelemetry Collector and
 are measured only for traces. In the future, more configurations will be tested.
 
-Note with the OpenCensus Agent you can expect as good if not better performance
-with lower resource utilization. This is because the OpenCensus Agent does not
+Note with the OpenTelemetry Agent you can expect as good if not better performance
+with lower resource utilization. This is because the OpenTelemetry Agent does not
 today support features such as batching or retries and will not support
 tail-sampling.
 
-It is important to note that the performance of the OpenCensus Collector depends
+It is important to note that the performance of the OpenTelemetry Collector depends
 on a variety of factors including:
 
-* The receiving format: OpenCensus (55678), Jaeger thrift (14268) or Zipkin v2 JSON (9411)
+* The receiving format: OpenTelemetry (55678), Jaeger thrift (14268) or Zipkin v2 JSON (9411)
 * The size of the spans (tests are based on number of attributes): 20
 * Whether tail-sampling is enabled or not
 * CPU / Memory allocation
@@ -35,8 +35,8 @@ impact the results of the tests. The parameters used are defined below.
 
 | Span<br>Format    | CPU<br>(2+ GHz) | RAM<br>(GB) | Sustained<br>Rate | Recommended<br>Maximum |
 | :---:             | :---:           | :---:       | :---:             | :---:                  |
-| OpenCensus        | 1               | 2           | ~12K              | 10K                    |
-| OpenCensus        | 2               | 4           | ~24K              | 20K                    |
+| OpenTelemetry        | 1               | 2           | ~12K              | 10K                    |
+| OpenTelemetry        | 2               | 4           | ~24K              | 20K                    |
 | Jaeger Thrift     | 1               | 2           | ~14K              | 12K                    |
 | Jaeger Thrift     | 2               | 4           | ~27.5K            | 24K                    |
 | Zipkin v2 JSON    | 1               | 2           | ~10.5K            | 9K                     |
@@ -56,8 +56,8 @@ service
 
 | Span<br>Format    | CPU<br>(2+ GHz) | RAM<br>(GB) | Sustained<br>Rate | Recommended<br>Maximum |
 | :---:             | :---:           | :---:       | :---:             | :---:                  |
-| OpenCensus        | 1               | 2           | ~9K               | 8K                     |
-| OpenCensus        | 2               | 4           | ~18K              | 16K                    |
+| OpenTelemetry        | 1               | 2           | ~9K               | 8K                     |
+| OpenTelemetry        | 2               | 4           | ~18K              | 16K                    |
 | Jaeger Thrift     | 1               | 6           | ~11.5K            | 10K                    |
 | Jaeger Thrift     | 2               | 8           | ~23K              | 20K                    |
 | Zipkin v2 JSON    | 1               | 6           | ~8.5K             | 7K                     |