From bbd491c00b974f5035fcd4013b778fb526fd6a91 Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Thu, 10 Jul 2025 18:15:24 +0200 Subject: [PATCH 1/4] Add proxy setting guide for EDOT --- docs/reference/edot-collector/config/proxy.md | 100 ++++++++++++++++++ docs/reference/toc.yml | 1 + 2 files changed, 101 insertions(+) create mode 100644 docs/reference/edot-collector/config/proxy.md diff --git a/docs/reference/edot-collector/config/proxy.md b/docs/reference/edot-collector/config/proxy.md new file mode 100644 index 00000000..eb4c8940 --- /dev/null +++ b/docs/reference/edot-collector/config/proxy.md @@ -0,0 +1,100 @@ +--- +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 Collector, proxy support applies to all exporters, including those using gRPC. No special configuration is needed beyond the environment variables. +::: + +## Proxy settings for EDOT SDKs + +With the exception of Java SDK, EDOT SDKs use the `HTTP_PROXY / HTTPS_PROXY` settings from environment variables and require no extra configuration. + +You can export environment variables like this: + +``` +export HTTP_PROXY=http://: +export HTTPS_PROXY=http://: +``` + +### 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](../../troubleshoot/ingest/opentelemetry/edot-sdks/java/proxy-issues.md) for more information. + +## Resources + +[Proxy support - upstream documentation](https://opentelemetry.io/docs/collector/configuration/#proxy-support) diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml index efa1803a..faa8aae9 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 From 4d065fbc9945ca60cf18d509bb32e7acb91dbc9a Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Thu, 10 Jul 2025 18:24:32 +0200 Subject: [PATCH 2/4] Update cross-repo link --- docs/reference/edot-collector/config/proxy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/edot-collector/config/proxy.md b/docs/reference/edot-collector/config/proxy.md index eb4c8940..7ad671b8 100644 --- a/docs/reference/edot-collector/config/proxy.md +++ b/docs/reference/edot-collector/config/proxy.md @@ -93,7 +93,7 @@ export HTTPS_PROXY=http://: ### 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](../../troubleshoot/ingest/opentelemetry/edot-sdks/java/proxy-issues.md) for more information. +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. ## Resources From 7ab501e543069ec10c18ad582481b6e287c1c462 Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Mon, 28 Jul 2025 16:01:23 +0200 Subject: [PATCH 3/4] Update the Collector proxy guide and create a new SDK proxy guide --- docs/reference/edot-collector/config/proxy.md | 18 ++------ docs/reference/edot-sdks/proxy.md | 45 +++++++++++++++++++ 2 files changed, 48 insertions(+), 15 deletions(-) create mode 100644 docs/reference/edot-sdks/proxy.md diff --git a/docs/reference/edot-collector/config/proxy.md b/docs/reference/edot-collector/config/proxy.md index 7ad671b8..820035e6 100644 --- a/docs/reference/edot-collector/config/proxy.md +++ b/docs/reference/edot-collector/config/proxy.md @@ -77,23 +77,11 @@ Environment="NO_PROXY=," :::: :::{{note}} -For the Collector, proxy support applies to all exporters, including those using gRPC. No special configuration is needed beyond the environment variables. -::: - -## Proxy settings for EDOT SDKs - -With the exception of Java SDK, EDOT SDKs use the `HTTP_PROXY / HTTPS_PROXY` settings from environment variables and require no extra configuration. - -You can export environment variables like this: +For the EDOT Collector, proxy support applies to all exporters, including those using gRPC. No special configuration is needed beyond the environment variables. -``` -export HTTP_PROXY=http://: -export HTTPS_PROXY=http://: -``` - -### Java SDK +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). +::: -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. ## Resources 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 From e59341790e0cb1483d9317de82022a2ca527c139 Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Mon, 28 Jul 2025 17:58:34 +0200 Subject: [PATCH 4/4] Add page to toc --- docs/reference/toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml index faa8aae9..4c7a631d 100644 --- a/docs/reference/toc.yml +++ b/docs/reference/toc.yml @@ -126,4 +126,5 @@ 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 \ No newline at end of file