Skip to content
This repository has been archived by the owner on Nov 7, 2022. It is now read-only.

Commit

Permalink
Update README for beta1 (#315)
Browse files Browse the repository at this point in the history
* Update README.md

Modifications for beta release:
* Add k8s example
* Fix broken links and remove zpages image
* Make agent and collector configuration consistent
* Fix syntax errors and version information
  • Loading branch information
flands authored Jan 16, 2019
1 parent 8e8c634 commit ec48630
Show file tree
Hide file tree
Showing 3 changed files with 224 additions and 46 deletions.
17 changes: 15 additions & 2 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ This document describes the architecture design and implementation of OpenCensus
OpenCensus Collector.

# Table of contents
- [Goals](#goals)
- [OpenCensus Agent](#opencensus-agent)
- [Architecture overview](#agent-architecture-overview)
- [Communication](#agent-communication)
Expand All @@ -15,7 +16,19 @@ OpenCensus Collector.
- [OpenCensus Collector](#opencensus-collector)
- [Architecture overview](#collector-architecture-overview)

## OpenCensus Agent
## <a name="goals"></a>Goals

* Allow enabling/configuring of exporters lazily. After deploying code,
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.
* 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="agent-architecture-overview"></a>Architecture Overview

Expand Down Expand Up @@ -136,7 +149,7 @@ 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.

## OpenCensus Collector
## <a name="opencensus-collector"></a>OpenCensus Collector

### <a name="collector-architecture-overview"></a>Architecture Overview

Expand Down
86 changes: 42 additions & 44 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,12 @@

# Table of contents
- [Introduction](#introduction)
- [Goals](#goals)
- [Deployment](#deploy-example)
- [Kubernetes](#deploy-k8s)
- [Standalone](#deploy-standalone)
- [Configuration](#config-file)
- [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)
Expand Down Expand Up @@ -47,26 +48,10 @@ Service will then automatically collect traces and metrics and export to any
backend of users' choice.

Currently the OpenCensus Service consists of two components,
[OpenCensus Agent](#opencensus-agent) and [OpenCensus Collector](#opencensus-collector).
High-level workflow:
[OpenCensus Agent](#opencensus-agent) and [OpenCensus Collector](#opencensus-collector). For the detailed design specs,
please see [DESIGN.md](DESIGN.md).

![service-architecture](images/opencensus-service.png)

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

## Goals

* Allow enabling/configuring of exporters lazily. After deploying code,
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.
* 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="deploy-example"></a>Deployment
## <a name="deploy"></a>Deployment

The OpenCensus Service can be deployed in a variety of different ways. The OpenCensus
Agent can be deployed with the application either as a separate process, as a sidecar,
Expand All @@ -75,13 +60,24 @@ separately as either a Docker container, VM, or Kubernetes pod.

![deployment-models](images/opencensus-service-deployment-models.png)

### <a name="deploy-k8s"></a>Kubernetes
## <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/census-instrumentation/opencensus-service/tree/master/demos/trace)

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

### <a name="deploy-standalone"></a>Standalone
Apply the [sample YAML](example/k8s.yaml) file:

Create an Agent [configuration file](#configuration-file) as described above.
```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. Please note the Agent
requires the `opencensus` receiver be enabled. By default, the Agent has no exporters configured.

Build the Agent, see [Building binaries](#agent-building-binaries),
and start it:
Expand All @@ -91,7 +87,8 @@ $ ./bin/ocagent_$(go env GOOS)
$ 2018/10/08 21:38:00 Running OpenCensus receiver as a gRPC service at "127.0.0.1:55678"
```

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

Build the Collector and start it:

Expand All @@ -110,15 +107,15 @@ 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-file"></a>Configuration
## <a name="config"></a>Configuration

The OpenCensus Service (both the Agent and Collector) is configured via a config.yaml file. In general, you need to
The OpenCensus 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

A receiver is how you get data into the OpenCensus Service. One or more receivers can be configured. By default,
the ``opencensus`` receiver is enabled on the OpenCensus Agent while no receivers are enabled on the OpenCensus Collector.
the `opencensus` receiver is enabled on the Collector and required as a defined receiver for the Agent.

A basic example of all available receivers is provided below. For detailed receiver configuration,
please see the [receiver README.md](receiver/README.md).
Expand All @@ -131,21 +128,21 @@ receivers:
address: "localhost:9411"

jaeger:
collector_thrift_port: 14267
collector_http_port: 14268
jaeger-thrift-tchannel-port: 14267
jaeger-thrift-http-port: 14268
```
### <a name="config-exporters"></a>Exporters
An exporter is how you send data to one or more backends/destinations. One or more exporters can be configured.
By default, no exporters are configured on the OpenCensus Agent or Collector.
By default, no exporters are configured on the OpenCensus Service (either the Agent or Collector).
A basic example of all available exporters is provided below. For detailed exporter configuration,
please see the [exporter README.md](exporter/exporterparser/README.md).
```yaml
exporters:
opencensus:
endpoint: "localhost:10001"
endpoint: "localhost:55678"

jaeger:
collector_endpoint: "http://localhost:14268/api/traces"
Expand Down Expand Up @@ -205,11 +202,6 @@ zpages:
disabled: true
```

and for example navigating to http://localhost:55679/debug/tracez to debug the
OpenCensus receiver's traces in your browser should produce something like this

![zPages](https://user-images.githubusercontent.com/4898263/47132981-892bb500-d25b-11e8-980c-08f0115ba72e.png)

## OpenCensus Agent

### <a name="agent-building-binaries"></a>Building binaries
Expand Down Expand Up @@ -272,7 +264,10 @@ For example, to create a Docker image of the agent, tagged `v1.0.0`:

and then the Docker image `v1.0.0` of the agent can be started by
```shell
docker run -v $(pwd)/config.yaml:/config.yaml -p 55678:55678 ocagent:v1.0.0
docker run --rm -it -p 55678:55678 -p 55679:55679 \
-v $(pwd)/ocagent-config.yaml:/conf/ocagent-config.yaml \
--config=/conf/ocagent-config.yaml \
ocagent:v1.0.0
```

A Docker scratch image can be built with make by targeting `docker-agent`.
Expand Down Expand Up @@ -325,7 +320,10 @@ $ ./bin/occollector_$($GOOS)
(note: additional ports may be required depending on your receiver configuration):
```shell
$ make docker-collector
$ docker run --rm -it -p 55678:55678 occollector
$ docker run --rm -it -p 55678:55678 -p 8888:8888 \
-v $(pwd)/occollector-config.yaml:/conf/occollector-config.yaml \
--config=/conf/occollector-config.yaml \
occollector
```

It can be configured via command-line or config file:
Expand Down Expand Up @@ -353,7 +351,7 @@ Sample configuration file:
log-level: DEBUG
receivers:
opencensus: {} # Runs OpenCensus receiver with default configuration
opencensus: {} # Runs OpenCensus receiver with default configuration (default behavior)
queued-exporters:
jaeger-sender-test: # A friendly name for the exporter
Expand Down
167 changes: 167 additions & 0 deletions example/k8s.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
---
apiVersion: v1
kind: ConfigMap
metadata:
name: oc-agent-conf
labels:
app: opencensus
component: oc-agent-conf
data:
oc-agent-config: |
receivers:
opencensus: {}
# jaeger: {}
# zipkin: {}
exporters:
opencensus:
endpoint: "oc-collector.default.svc.cluster.local:55678" # TODO: Update me
---
apiVersion: extensions/v1beta1
kind: DaemonSet
metadata:
name: oc-agent
labels:
app: opencensus
component: oc-agent
spec:
template:
metadata:
labels:
app: opencensus
component: oc-agent
spec:
containers:
- image: omnition/opencensus-agent:1.1.2
name: oc-agent
resources:
limits:
cpu: 0.5
memory: 500Mi
command:
- "ocagent_linux"
- "--config-file=/conf/oc-agent-config.yaml"
ports:
- containerPort: 55678
- containerPort: 55679
# - containerPort: 14267
# - containerPort: 14268
# - containerPort: 9411
volumeMounts:
- name: oc-agent-config-vol
mountPath: /conf
volumes:
- configMap:
name: oc-agent-conf
items:
- key: oc-agent-config
path: oc-agent-config.yaml
name: oc-agent-config-vol
---
apiVersion: v1
kind: ConfigMap
metadata:
name: oc-collector-conf
labels:
app: opencensus
component: oc-collector-conf
data:
oc-collector-config: |
receivers:
opencensus: {}
jaeger: {}
zipkin: {}
# Can only use one exporter
# exporters:
# jaeger:
# collector_endpoint: "http://jaeger.default.svc.cluster.local:14268/api/traces"
# zipkin: {}
queued-exporters:
omnition:
num-workers: 20
queue-size: 10000
retry-on-failure: true
sender-type: jaeger-thrift-http
jaeger-thrift-http:
collector_endpoint: https://ingest.omnition.io/api/traces
headers: { "x-omnition-api-key":"00000000-0000-0000-0000-000000000001" } # TODO: Update me
timeout: 5s
---
apiVersion: v1
kind: Service
metadata:
name: oc-collector
labels:
app: opencesus
component: oc-collector
spec:
ports:
- name: opencensus
port: 55678
protocol: TCP
targetPort: 55678
# - name: jaeger-tchannel
# port: 14267
# - name: jaeger-thrift-http
# port: 14268
# - name: zipkin
# port: 9411
selector:
component: oc-collector
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: oc-collector
labels:
app: opencensus
component: oc-collector
spec:
minReadySeconds: 5
progressDeadlineSeconds: 120
replicas: 1
template:
metadata:
annotations:
prometheus.io/path: "/metrics"
prometheus.io/port: "8888"
prometheus.io/scrape: "true"
labels:
app: opencensus
component: oc-collector
spec:
containers:
- image: omnition/opencensus-collector:1.1.2
name: oc-collector
resources:
limits:
cpu: 1
memory: 2Gi
requests:
cpu: 200m
memory: 400Mi
command:
- "occollector_linux"
- "--config-file=/conf/oc-collector-config.yaml"
ports:
- containerPort: 55678
# - containerPort: 14267
# - containerPort: 14268
# - containerPort: 9411
volumeMounts:
- name: oc-collector-config-vol
mountPath: /conf
livenessProbe:
httpGet:
path: /
port: 13133
readinessProbe:
httpGet:
path: /
port: 13133
volumes:
- configMap:
name: oc-collector-conf
items:
- key: oc-collector-config
path: oc-collector-config.yaml
name: oc-collector-config-vol

0 comments on commit ec48630

Please sign in to comment.