OpenCensus Service Configuration
Published by Steve Flanders on
In my last post, I talked about what the OpenCensus Service is and why you should care. After reading that post, you are likely wondering how to get started. In this post, I would like to walk through how to deploy and configure the OpenCensus Service in a greenfield or brownfield environment.
(Spoiler alert: it is really easy!)
The best practice when deploying the OpenCensus Service is to use the latest release. While you can always build from master, a release reduces the number of steps you need to perform and ensures stability. The OpenCensus Service SIG currently works on a two-week sprint cadence and typically releases a new version at the end of the sprint. You can track the latest milestone in order to figure out what is coming next.
There are three deployment options for the Agent (listed in order of preference):
Preference is determined based on the available resources and security concerns. For example, daemonsets are typically more resource efficient than running an Agent as a sidecar, but the security vector is larger in this deployment model. No matter which deployment model you choose, the mapping is always 1:1 (e.g. one Agent per host for daemonset or one Agent per service for sidecar).
The Collector can be deployed as a binary or container. In either case, it should be deployed as a standalone service. The Collector can be scaled up or out as needed. Performance information can be found on Github (more on OpenCensus Service performance in a future post).
Configuration of the OpenCensus Service is generally done via YAML (though the
Collector also offers CLI configuration flags). Both the Agent and Collector
listen for incoming traffic on port
55678 (OpenCensus receiver) and have no
exporter configured by default. Both also expose z-pages on port
55679 (more on
z-pages in a future post), which can be used to troubleshoot the OpenCensus
Service. The Agent and Collector are based on the same code base and, as a
result, share many of the same features and configuration options.
Whether working with the Agent or the Collector, configuring receivers is the same. Here is an example configuration to enable additional receivers:
To simplify operations, the OpenCensus receiver is enabled by default, and only needs to be specified when a custom receiver configuration is desired.
Protip: If you wish to enable a receiver with the default configuration, you
can do so by specifying the receiver without any parameters. For example, the
following is equivalent to the
jaeger configurations above:
As mentioned above, the Agent (like the Collector) does not send data to any
destination by default. Destinations can be specified by configuring one or
exporters. The recommended exporter configuration for the Agent would be
to the OpenCensus Collector (via the opencensus exporter). For example:
While there are other configuration options for the Agent, the
exporters sections are the only commonly changed options.
Like the Agent, exporting needs to be configured on the Collector. One
difference with the Collector is that it leverages
offers many additional configuration options. For example:
In general, the backend you wish to export to will have a recommended default configuration. The only configuration a user needs to specify is where the destination is and how to authenticate, if applicable.
In addition to
exporters, it may be necessary to specify others configuration
options in the Collector. For example:
- You may wish to add attributes to all spans received by a given Collector (e.g. datacenter, region, or zone)
- You may wish to redact an attribute before forwarding it to the backend of your choice (e.g. for security reasons)
- You may wish to rename an attribute (e.g. to support semantic conventions)
All of this can be done by configuring global attributes. For example:
Another options in the Collector is the ability to configure intelligent (tail-based) sampling. This allows for sampling decisions to be made from complete traces instead of when a trace starts (more on intelligent sampling in a future post). For example:
Finally, the Collector also offers command-line flags to enable functionality (i.e. without manually editing or supplying the configuration). The parameters available today are:
While it may look like there are a lot of configuration options for the OpenCensus Service, the repository has some great resources to get you started quickly. If you are on Kubernetes, an example YAML file is provided. Otherwise, deployment options for running locally or via a container are provided in the README.
Some things to note regarding configuration:
- Leverage the CLI options in the Collector and the defaults whenever possible
- The only configuration you need to supply for either the Agent or the
exporters(though other options may be necessary depending on business requirements)
- In general, the Agent should export to the Collector and the Collector should export to the backend(s) of your choice.
If you are interested in learning more about the OpenCensus Service
configuration options, take a look at the OpenCensus Service documentation or
the README. If you are interested in getting involved in the project,
drop me an email at steve at omnition dot io or direct message me on Gitter
@flands. In addition, take a look at our