diff --git a/docs/reference/edot-collector/config/proxy.md b/docs/reference/edot-collector/config/proxy.md new file mode 100644 index 00000000..820035e6 --- /dev/null +++ b/docs/reference/edot-collector/config/proxy.md @@ -0,0 +1,88 @@ +--- +navigation_title: Proxy settings +description: Configuration of the EDOT Collector's proxy settings. +applies_to: + stack: + serverless: + observability: + product: + edot_collector: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-collector +--- + +# Configure proxy settings for EDOT components + +When running Elastic Distributions of OpenTelemetry (EDOT) in environments that require outbound traffic to go through a proxy, you must explicitly configure proxy settings. + +You may need to configure a proxy if: + +- Your app is deployed behind a corporate proxy or firewall. +- Your telemetry is sent to Elastic APM in Elastic Cloud or another hosted destination. +- Network errors such as `Connection timed out` or `SSL handshake failed` appear in logs. + +## Available proxy variables + +| Variable | Description | +|--------------|---------------------------------------------| +| HTTP_PROXY | URL of the proxy server for HTTP requests | +| HTTPS_PROXY | URL of the proxy server for HTTPS requests | +| NO_PROXY | Comma-separated list of hosts to exclude | + +## Configure proxy settings for the EDOT Collector + +Most EDOT components honor common proxy environment variables. The following examples show how to configure them: + +::::{tab-set} + +:::{tab-item} Docker run +```bash +docker run -e HTTP_PROXY=http://: \ + -e HTTPS_PROXY=http://: \ + otel/opentelemetry-collector:latest +``` +::: + +:::{tab-item} Docker compose +```yaml +services: + edotcollector: + environment: + - HTTP_PROXY=http://: + - HTTPS_PROXY=http://: +``` +::: + +:::{tab-item} Kubernetes pod manifest +```yaml +env: + - name: HTTP_PROXY + value: ':' + - name: HTTPS_PROXY + value: ':' +``` +::: + +:::{tab-item} systemmd [Service] unit file +``` +[Service] +Environment="HTTP_PROXY=http://:" +Environment="HTTPS_PROXY=http://:" +Environment="NO_PROXY=," +``` +::: + +:::: + +:::{{note}} +For the EDOT Collector, proxy support applies to all exporters, including those using gRPC. No special configuration is needed beyond the environment variables. + +If you're using an SDK that doesn't support proxy variables directly, consider routing telemetry through an EDOT Collector configured with proxy settings. This ensures consistent proxy handling. For more information, refer to [Proxy settings for EDOT SDKs](../../edot-sdks/proxy.md). +::: + + +## Resources + +[Proxy support - upstream documentation](https://opentelemetry.io/docs/collector/configuration/#proxy-support) diff --git a/docs/reference/edot-sdks/proxy.md b/docs/reference/edot-sdks/proxy.md new file mode 100644 index 00000000..32becc96 --- /dev/null +++ b/docs/reference/edot-sdks/proxy.md @@ -0,0 +1,45 @@ +--- +navigation_title: Proxy settings +description: Configuration of the EDOT SDKs proxy settings. +applies_to: + stack: + serverless: + observability: + product: + edot_collector: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-collector +--- + +# Proxy settings for EDOT SDKs + +EDOT SDKs generally use the standard proxy environment variables. However, there are exceptions and limitations depending on the language and exporter type. + +## Python SDK + +The Python SDK honors `HTTP_PROXY` and `HTTPS_PROXY` only when using the `http/protobuf` exporter. + +If you use the default gRPC-based exporter, proxy settings are ignored. To enable proxy support, you can either: + +* Switch to the `http/protobuf` exporter, which supports standard proxy environment variables. + +* Route telemetry through a local EDOT Collector configured with proxy settings. + +## Node.js SDK + +The Node.js SDK does not currently support `HTTP_PROXY`, `HTTPS_PROXY`, or `NO_PROXY` by default. You can route telemetry through an EDOT Collector. + +## Java SDK + +If you’re using Java SDK, you must configure Java system properties using the Java Virtual Machine (JVM). Refer to [Troubleshooting Java SDK proxy issues](docs-content://troubleshoot/ingest/opentelemetry/edot-sdks/java/proxy-issues.md) for more information. + +## Other SDKs + +Other EDOT SDKs honor standard proxy environment variables with no additional setup required. For example: + +``` +export HTTP_PROXY=http://: +export HTTPS_PROXY=http://: +``` \ No newline at end of file diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml index 2dd8940f..369798bf 100644 --- a/docs/reference/toc.yml +++ b/docs/reference/toc.yml @@ -51,6 +51,7 @@ toc: - file: edot-collector/config/default-config-k8s.md - file: edot-collector/config/configure-logs-collection.md - file: edot-collector/config/configure-metrics-collection.md + - file: edot-collector/config/proxy.md - file: edot-collector/customization.md children: - file: edot-collector/components.md @@ -124,5 +125,6 @@ toc: - file: edot-sdks/python/supported-technologies.md - file: edot-sdks/python/migration.md - file: edot-sdks/python/overhead.md + - file: edot-sdks/proxy.md - file: motlp.md - - file: central-configuration.md \ No newline at end of file + - file: central-configuration.md