From 9c05f84065f61cfb864e2cdce465bbabaabb2b92 Mon Sep 17 00:00:00 2001 From: Steve Flanders Date: Tue, 19 May 2020 13:29:41 -0400 Subject: [PATCH] Add OTLP receiver docs (#980) * Add OTLP receiver docs * Also move hostmetrics docs here * Fix broken links * Other minor cleanup * Address feedback * Address feedback --- receiver/README.md | 136 ++++++++++++++++++++++--- receiver/hostmetricsreceiver/README.md | 43 -------- 2 files changed, 120 insertions(+), 59 deletions(-) delete mode 100644 receiver/hostmetricsreceiver/README.md diff --git a/receiver/README.md b/receiver/README.md index 39e35d8fa54..c2113b2307d 100644 --- a/receiver/README.md +++ b/receiver/README.md @@ -8,12 +8,14 @@ The format of the traces and metrics supported are receiver specific. Supported trace receivers (sorted alphabetically): - [Jaeger Receiver](#jaeger) -- [OpenCensus Receiver](#opencensus) +- [OpenCensus Receiver](#opencensus-traces) +- [OpenTelemetry Receiver](#otlp-traces) - [Zipkin Receiver](#zipkin) Supported metric receivers (sorted alphabetically): - [Host Metrics Receiver](#hostmetrics) -- [OpenCensus Receiver](#opencensus) +- [OpenCensus Receiver](#opencensus-metrics) +- [OpenTelemetry Receiver](#otlp-metrics) - [Prometheus Receiver](#prometheus) - [VM Metrics Receiver](#vmmetrics) @@ -97,29 +99,30 @@ receivers: ``` ### Remote Sampling -The Jaeger receiver also supports fetching sampling configuration from a remote collector. -It works by proxying client requests for remote sampling configuration to the configured collector. +The Jaeger receiver also supports fetching sampling configuration from a remote +collector. It works by proxying client requests for remote sampling +configuration to the configured collector. -+---------------+ +--------------+ +-----------------+ -| | get | | proxy | | -| client +--- sampling ---->+ agent +------------->+ collector | -| | strategy | | | | -+---------------+ +--------------+ +-----------------+ + +------------+ +-----------+ +---------------+ + | | get | | proxy | | + | client +--- sampling ---->+ agent +------------->+ collector | + | | strategy | | | | + +------------+ +-----------+ +---------------+ -Remote sample proxying can be enabled by specifying the following lines in the jaeger receiver config: +Remote sample proxying can be enabled by specifying the following lines in the +jaeger receiver config: ```yaml receivers: jaeger: protocols: grpc: - . - . remote_sampling: fetch_endpoint: "jaeger-collector:1234" -``` +``` -Remote sampling can also be directly served by the collector by providing a sampling json file: +Remote sampling can also be directly served by the collector by providing a +sampling json file: ```yaml receivers: @@ -128,9 +131,10 @@ receivers: grpc: remote_sampling: strategy_file: "/etc/strategy.json" -``` +``` -Note: gRPC must be enabled for this to work as Jaeger serves its remote sampling strategies over gRPC. +Note: gRPC must be enabled for this to work as Jaeger serves its remote +sampling strategies over gRPC. ## OpenCensus Receiver @@ -184,6 +188,60 @@ receivers: - https://*.example.com ``` +## OpenTelemetry Receiver + +This is the default receiver for the OpenTelemetry project. + +To get started, all that is required to enable the OpenTelemetry receiver is to +include it in the receiver definitions. This will enable the default values as +specified [here](otlpreceiver/factory.go). +The following is an example: +```yaml +receivers: + otlp: +``` + +The full list of settings exposed for this receiver are documented [here](otlpreceiver/config.go) +with detailed sample configurations [here](otlpreceiver/testdata/config.yaml). + +### Communicating over TLS +This receiver supports communication using Transport Layer Security (TLS). TLS +can be configured by specifying a `tls_credentials` object in the receiver +configuration for receivers that support it. +```yaml +receivers: + otlp: + tls_credentials: + key_file: /key.pem # path to private key + cert_file: /cert.pem # path to certificate +``` + +### Writing with HTTP/JSON +The OpenTelemetry receiver can receive trace export calls via HTTP/JSON in +addition to gRPC. The HTTP/JSON address is the same as gRPC as the protocol is +recognized and processed accordingly. Note the format needs to be [protobuf +JSON +serialization](https://developers.google.com/protocol-buffers/docs/proto3#json). + +IMPORTANT: bytes fields are encoded as base64 strings. + +To write traces with HTTP/JSON, `POST` to +`[address]/v1/trace`. + +The HTTP/JSON endpoint can also optionally configure +[CORS](https://fetch.spec.whatwg.org/#cors-protocol), which is enabled by +specifying a list of allowed CORS origins in the `cors_allowed_origins` field: + +```yaml +receivers: + otlp: + endpoint: "localhost:55680" + cors_allowed_origins: + - http://test.com + # Origins can have wildcards with *, use * by itself to match any origin. + - https://*.example.com +``` + ## Zipkin Receiver This receiver receives spans from [Zipkin](https://zipkin.io/) (V1 and V2). @@ -202,11 +260,57 @@ with detailed sample configurations [here](zipkinreceiver/testdata/config.yaml). # Metric Receivers +## Host Metrics Receiver + +The Host Metrics receiver generates metrics about the host system. This is +intended to be used when the collector is deployed as an agent. + +The categories of metrics scraped can be configured under the `scrapers` key. +For example: + +```yaml +hostmetrics: + collection_interval: 1m + scrapers: + cpu: + memory: + disk: +``` + +If you would like to scrape some metrics at a different frequency than others, +you can configure multiple `hostmetrics` receivers with different +`collection_interval values`. For example: + +```yaml +receivers: + hostmetrics: + collection_interval: 30s + scrapers: + cpu: + memory: + + hostmetrics/disk: + collection_interval: 1m + scrapers: + disk: + filesystem: + +service: + pipelines: + metrics: + receivers: [hostmetrics, hostmetrics/disk] +``` + ## OpenCensus Receiver The OpenCensus receiver supports both traces and metrics. Configuration information can be found under the trace section [here](#opencensus-traces). +## OpenTelemetry Receiver + +The OpenTelemetry receiver supports both traces and metrics. Configuration +information can be found under the trace section [here](#otlp-traces). + ## Prometheus Receiver This receiver is a drop-in replacement for getting Prometheus to scrape your diff --git a/receiver/hostmetricsreceiver/README.md b/receiver/hostmetricsreceiver/README.md deleted file mode 100644 index c0aa129a93d..00000000000 --- a/receiver/hostmetricsreceiver/README.md +++ /dev/null @@ -1,43 +0,0 @@ -# Host Metrics Receiver - -The Host Metrics receiver generates metrics about the host system. This is intended to be used when the collector is -deployed as an agent. - -The categories of metrics scraped can be configured under the `scrapers` key, e.g. to scrape cpu, memory and disk metrics: - -```yaml -hostmetrics: - collection_interval: 1m - scrapers: - cpu: - memory: - disk: -``` - -If you would like to scrape some metrics at a different frequency than others, you can configure multiple hostmetrics -receivers with different collection_interval values, e.g. - -```yaml -receivers: - hostmetrics: - collection_interval: 30s - scrapers: - cpu: - memory: - - hostmetrics/disk: - collection_interval: 1m - scrapers: - disk: - filesystem: - -service: - pipelines: - metrics: - receivers: [hostmetrics, hostmetrics/disk] -``` - -## OS Support - -The initial implementation of the Host Metrics receiver supports Windows only. It's intended that future iterations -of this receiver will support the collection of identical metrics (where possible) on other operating systems.