Add README to config components (open-telemetry#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 <[email protected]>

* Update config/confighttp/README.md

Co-authored-by: Tigran Najaryan <[email protected]>

* Update config/confighttp/README.md

Co-authored-by: Tigran Najaryan <[email protected]>

* Update config/confighttp/README.md

* Fix broken links

* Update README.md

Co-authored-by: Tigran Najaryan <[email protected]>

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)

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:
+```

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.

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
+```

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).

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)

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.