From ee64e795087b933f01ceaa17f61ff9229fdda44a Mon Sep 17 00:00:00 2001 From: Steve Flanders Date: Mon, 9 Nov 2020 13:02:08 -0500 Subject: [PATCH] Add README to config components (#2072) * Add README to config components This can be linked to receivers and exporters in a future PR. * Update config/configgrpc/README.md Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> * Update config/confighttp/README.md Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> * Update config/confighttp/README.md Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> * Update config/confighttp/README.md * Fix broken links * Update README.md Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> --- config/configgrpc/README.md | 62 ++++++++++++++++++ config/confighttp/README.md | 56 +++++++++++++++++ config/confignet/README.md | 18 ++++++ config/configtls/README.md | 100 ++++++++++++++++++++++++++++++ docs/pipelines.md | 4 -- exporter/exporterhelper/README.md | 3 +- processor/README.md | 9 +-- receiver/README.md | 5 +- 8 files changed, 245 insertions(+), 12 deletions(-) create mode 100644 config/configgrpc/README.md create mode 100644 config/confighttp/README.md create mode 100644 config/confignet/README.md create mode 100644 config/configtls/README.md delete mode 100644 docs/pipelines.md diff --git a/config/configgrpc/README.md b/config/configgrpc/README.md new file mode 100644 index 0000000000000..4a6ff017b6dc8 --- /dev/null +++ b/config/configgrpc/README.md @@ -0,0 +1,62 @@ +# gRPC Configuration Settings + +gRPC exposes a [variety of settings](https://godoc.org/google.golang.org/grpc). +Several of these settings are available for configuration within individual +receivers or exporters. In general, none of these settings should need to be +adjusted. + +## Client Configuration + +[Exporters](https://github.com/open-telemetry/opentelemetry-collector/blob/master/exporter/README.md) +leverage client configuration. + +Note that client configuration supports TLS configuration, however +configuration parameters are not defined under `tls_settings` like server +configuration. For more information, see [configtls +README](../configtls/README.md). + +- [`balancer_name`](https://github.com/grpc/grpc-go/blob/master/examples/features/load_balancing/README.md) +- `compression` (default = gzip): Compression type to use (only gzip is supported today) +- `endpoint`: Valid value syntax available [here](https://github.com/grpc/grpc/blob/master/doc/naming.md) +- `headers`: name/value pairs added to the request +- [`keepalive`](https://godoc.org/google.golang.org/grpc/keepalive#ClientParameters) + - `permit_without_stream` + - `time` + - `timeout` +- [`read_buffer_size`](https://godoc.org/google.golang.org/grpc#ReadBufferSize) +- [`write_buffer_size`](https://godoc.org/google.golang.org/grpc#WriteBufferSize) + +Example: + +```yaml +exporter: + otlp: + endpoint: otelcol2:55690 + headers: + test1: "value1" + "test 2": "value 2" +``` + +## Server Configuration + +[Receivers](https://github.com/open-telemetry/opentelemetry-collector/blob/master/receiver/README.md) +leverage server configuration. + +Note that transport configuration can also be configured. For more information, +see [confignet README](../confignet/README.md). + +- [`keepalive`](https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters) + - [`enforcement_policy`](https://godoc.org/google.golang.org/grpc/keepalive#EnforcementPolicy) + - `min_time` + - `permit_without_stream` + - [`server_parameters`](https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters) + - `max_connection_age` + - `max_connection_age_grace` + - `max_connection_idle` + - `time` + - `timeout` +- [`max_concurrent_streams`](https://godoc.org/google.golang.org/grpc#MaxConcurrentStreams) +- [`max_recv_msg_size_mib`](https://godoc.org/google.golang.org/grpc#MaxRecvMsgSize) +- [`read_buffer_size`](https://godoc.org/google.golang.org/grpc#ReadBufferSize) +- [`tls_settings`](../configtls/README.md) +- [`write_buffer_size`](https://godoc.org/google.golang.org/grpc#WriteBufferSize) diff --git a/config/confighttp/README.md b/config/confighttp/README.md new file mode 100644 index 0000000000000..5449b6793335e --- /dev/null +++ b/config/confighttp/README.md @@ -0,0 +1,56 @@ +# HTTP Configuration Settings + +HTTP exposes a [variety of settings](https://golang.org/pkg/net/http/). +Several of these settings are available for configuration within individual +receivers or exporters. + +## Client Configuration + +[Exporters](https://github.com/open-telemetry/opentelemetry-collector/blob/master/exporter/README.md) +leverage client configuration. + +Note that client configuration supports TLS configuration, however +configuration parameters are not defined under `tls_settings` like server +configuration. For more information, see [configtls +README](../configtls/README.md). + +- `endpoint`: address:port +- `headers`: name/value pairs added to the HTTP request headers +- [`read_buffer_size`](https://golang.org/pkg/net/http/#Transport) +- [`timeout`](https://golang.org/pkg/net/http/#Client) +- [`write_buffer_size`](https://golang.org/pkg/net/http/#Transport) + +Example: + +```yaml +exporter: + otlp: + endpoint: otelcol2:55690 + headers: + test1: "value1" + "test 2": "value 2" +``` + +## Server Configuration + +[Receivers](https://github.com/open-telemetry/opentelemetry-collector/blob/master/receiver/README.md) +leverage server configuration. + +- [`cors_allowed_origins`](https://github.com/rs/cors): An empty list means + that CORS is not enabled at all. A wildcard can be used to match any origin + or one or more characters of an origin. +- `endpoint`: Valid value syntax available [here](https://github.com/grpc/grpc/blob/master/doc/naming.md) +- [`tls_settings`](../configtls/README.md) + +Example: + +```yaml +receivers: + otlp: + cors_allowed_origins: + - https://foo.bar.com + - https://*.test.com + endpoint: 0.0.0.0:55690 + protocols: + http: +``` diff --git a/config/confignet/README.md b/config/confignet/README.md new file mode 100644 index 0000000000000..2a4053da59fa7 --- /dev/null +++ b/config/confignet/README.md @@ -0,0 +1,18 @@ +# Network Configuration Settings + +[Receivers](https://github.com/open-telemetry/opentelemetry-collector/blob/master/receiver/README.md) +leverage network configuration to set connection and transport information. + +- `endpoint`: Configures the address for this network connection. For TCP and + UDP networks, the address has the form "host:port". The host must be a + literal IP address, or a host name that can be resolved to IP addresses. The + port must be a literal port number or a service name. If the host is a + literal IPv6 address it must be enclosed in square brackets, as in + "[2001:db8::1]:80" or "[fe80::1%zone]:80". The zone specifies the scope of + the literal IPv6 address as defined in RFC 4007. +- `transport`: Known protocols are "tcp", "tcp4" (IPv4-only), "tcp6" + (IPv6-only), "udp", "udp4" (IPv4-only), "udp6" (IPv6-only), "ip", "ip4" + (IPv4-only), "ip6" (IPv6-only), "unix", "unixgram" and "unixpacket". + +Note that for TCP receivers only the `endpoint` configuration setting is +required. diff --git a/config/configtls/README.md b/config/configtls/README.md new file mode 100644 index 0000000000000..02fd5931655bf --- /dev/null +++ b/config/configtls/README.md @@ -0,0 +1,100 @@ +# TLS Configuration Settings + +Crypto TLS exposes a [variety of settings](https://godoc.org/crypto/tls). +Several of these settings are available for configuration within individual +receivers or exporters. + +Note that mutual TLS (mTLS) is also supported. + +## TLS / mTLS Configuration + +By default, TLS is enabled: + +- `insecure` (default = false): whether to enable client transport security for + the exporter's gRPC connection. See + [grpc.WithInsecure()](https://godoc.org/google.golang.org/grpc#WithInsecure). + +As a result, the following parameters are also required: + +- `cert_file`: Path to the TLS cert to use for TLS required connections. Should + only be used if `insecure` is set to false. +- `key_file`: Path to the TLS key to use for TLS required connections. Should + only be used if `insecure` is set to false. + +A certificate authority may also need to be defined: + +- `ca_file`: Path to the CA cert. For a client this verifies the server + certificate. For a server this verifies client certificates. If empty uses + system root CA. Should only be used if `insecure` is set to false. + +How TLS/mTLS is configured depends on whether configuring the client or server. +See below for examples. + +## Client Configuration + +[Exporters](https://github.com/open-telemetry/opentelemetry-collector/blob/master/exporter/README.md) +leverage client configuration. + +Note that client configuration supports TLS configuration, however +configuration parameters are not defined under `tls_settings` like server +configuration. For more information, see [configtls +README](../configtls/README.md). + +Beyond TLS configuration, the following setting can optionally be configured: + +- `server_name_override`: If set to a non-empty string, it will override the + virtual host name of authority (e.g. :authority header field) in requests + (typically used for testing). + +Example: + +```yaml +exporters: + otlp: + endpoint: myserver.local:55690 + insecure: false + ca_file: server.crt + cert_file: client.crt + key_file: client.key + otlp/insecure: + endpoint: myserver.local:55690 + insecure: true +``` + +## Server Configuration + +[Receivers](https://github.com/open-telemetry/opentelemetry-collector/blob/master/receiver/README.md) +leverage server configuration. + +Beyond TLS configuration, the following setting can optionally be configured +(required for mTLS): + +- `client_ca_file`: Path to the TLS cert to use by the server to verify a + client certificate. (optional) This sets the ClientCAs and ClientAuth to + RequireAndVerifyClientCert in the TLSConfig. Please refer to + https://godoc.org/crypto/tls#Config for more information. + +Example: + +```yaml +receivers: + otlp: + protocols: + grpc: + endpoint: mysite.local:55690 + tls_settings: + cert_file: server.crt + key_file: server.key + otlp/mtls: + protocols: + grpc: + client_ca_file: client.pem + endpoint: mysite.local:55690 + tls_settings: + cert_file: server.crt + key_file: server.key + otlp/notls: + protocols: + grpc: + endpoint: mysite.local:55690 +``` diff --git a/docs/pipelines.md b/docs/pipelines.md deleted file mode 100644 index 2e7af35074c97..0000000000000 --- a/docs/pipelines.md +++ /dev/null @@ -1,4 +0,0 @@ -# Pipelines -*Note* This documentation is still in progress. For any questions, please reach -out in the [OpenTelemetry Gitter](https://gitter.im/open-telemetry/opentelemetry-service) -or refer to the [issues page](https://github.com/open-telemetry/opentelemetry-collector/issues). \ No newline at end of file diff --git a/exporter/exporterhelper/README.md b/exporter/exporterhelper/README.md index be47eb61c1f23..64c3893ecd480 100644 --- a/exporter/exporterhelper/README.md +++ b/exporter/exporterhelper/README.md @@ -23,5 +23,6 @@ The following configuration options can be modified: - `requests_per_second` is the average number of requests per seconds. - `resource_to_telemetry_conversion` - `enabled` (default = false): If `enabled` is `true`, all the resource attributes will be converted to metric labels by default. +- `timeout` (defult = 5s): Time to wait per individual attempt to send data to a backend. -The full list of settings exposed for this helper exporter are documented [here](factory.go). +The full list of settings exposed for this helper exporter are documented [here](factory.go). \ No newline at end of file diff --git a/processor/README.md b/processor/README.md index e752cfd981cf4..8aea59295bdd7 100644 --- a/processor/README.md +++ b/processor/README.md @@ -1,8 +1,9 @@ # General Information -Processors are used at various stages of a [pipeline](../docs/pipelines.md). -Generally, a processor pre-processes data before it is exported (e.g. -modify attributes or sample) or helps ensure that data makes it through a -pipeline successfully (e.g. batch/retry). + +Processors are used at various stages of a pipeline. Generally, a processor +pre-processes data before it is exported (e.g. modify attributes or sample) or +helps ensure that data makes it through a pipeline successfully (e.g. +batch/retry). Some important aspects of pipelines and processors to be aware of: - [Recommended Processors](#recommended-processors) diff --git a/receiver/README.md b/receiver/README.md index ebe4be8ad2aac..a9cbffd1dfd3a 100644 --- a/receiver/README.md +++ b/receiver/README.md @@ -3,7 +3,7 @@ A receiver is how data gets into the OpenTelemetry Collector. Generally, a recei accepts data in a specified format, translates it into the internal format and passes it to [processors](../processor/README.md) and [exporters](../exporter/README.md) -defined in the applicable [pipelines](../docs/pipelines.md). +defined in the applicable pipelines. The format of the traces and metrics supported are receiver specific. Supported trace receivers (sorted alphabetically): @@ -51,5 +51,4 @@ must be unique. For the example above: - Receiver 2 has full name `examplereceiver/settings`. All receivers expose a setting to disable it, by default receivers are enabled. -At least one receiver must be enabled per [pipeline](../docs/pipelines.md) to be a -valid configuration. +At least one receiver must be enabled per pipeline to be a valid configuration.