From 2acb426d0d17111efb1d70fb33dc27f8eb7f0c57 Mon Sep 17 00:00:00 2001 From: Lingling Peng Date: Tue, 21 Oct 2025 14:43:50 -0400 Subject: [PATCH 1/5] update signoz export documentation --- .env.example | 6 +++--- README.md | 45 ++++++++++++++++++++++----------------------- setup.cfg | 1 + 3 files changed, 26 insertions(+), 26 deletions(-) diff --git a/.env.example b/.env.example index fe67bd73c..b02b3acd6 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,6 @@ ## Here are the environment variables you can set for the Synapse Python client to configure OpenTelemetry tracing and metrics: # You can copy this file to `.env` and fill in the values as needed. # OTEL_SERVICE_NAME=my-service-using-synapse-python-client -# OTEL_EXPORTER_OTLP_ENDPOINT=http://fill-me-in -# OTEL_SERVICE_INSTANCE_ID=local_development_testing -# OTEL_EXPORTER_OTLP_HEADERS=# Authorization +# OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.us.signoz.cloud +# OTEL_SERVICE_INSTANCE_ID=local +# OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key= diff --git a/README.md b/README.md index e1db0e358..a31ea2826 100644 --- a/README.md +++ b/README.md @@ -280,36 +280,31 @@ OpenTelemetry (OTEL) Read more about OpenTelemetry in Python [here](https://opentelemetry.io/docs/instrumentation/python/) -### Quick-start -The following shows an example of setting up [jaegertracing](https://www.jaegertracing.io/docs/1.50/deployment/#all-in-one) via docker and executing a simple python script that implements the Synapse Python client. +### Exporting Synapse Client Traces to SigNoz Cloud for developers -#### Running the jaeger docker container -Start a docker container with the following options: -``` -docker run --name jaeger \ - -e COLLECTOR_OTLP_ENABLED=true \ - -p 16686:16686 \ - -p 4318:4318 \ - jaegertracing/all-in-one:latest -``` -Explanation of ports: -* `4318` HTTP port for OTLP data collection -* `16686` Jaeger UI for visualizing traces - -Once the docker container is running you can access the Jaeger UI via: `http://localhost:16686` +#### Prerequisites +1. Create an account and obtain access to Signoz Cloud. +2. Create an ingestion key by following the step [here](https://signoz.io/docs/ingestion/signoz-cloud/keys/). #### Environment Variable Configuration - -By default, the OTEL exporter sends trace data to `http://localhost:4318/v1/traces`. You can customize the behavior through environment variables: - -* `OTEL_SERVICE_NAME`: Defines a unique identifier for your application or service in telemetry data (defaults to 'synapseclient'). Set this to a descriptive name that represents your specific implementation, making it easier to filter and analyze traces in your monitoring system. -* `OTEL_EXPORTER_OTLP_ENDPOINT`: Specifies the destination URL for sending telemetry data (defaults to 'http://localhost:4318'). Configure this to direct data to your preferred OpenTelemetry collector or monitoring service. +The following environment variables are required to be set: +- `OTEL_EXPORTER_OTLP_HEADERS`: `signoz-ingestion-key=` +- `OTEL_EXPORTER_OTLP_ENDPOINT`: `https://ingest.us.signoz.cloud` +- `OTEL_SERVICE_NAME`: `your-service-name` + +Explanation of both required and optional environment variables: +##### Required +* `OTEL_EXPORTER_OTLP_ENDPOINT`: The OTLP endpoint to which telemetry is exported. +* `OTEL_EXPORTER_OTLP_HEADERS`: Authentication/metadata for exports (e.g., API keys, tokens). For SigNoz, use `signoz-ingestion-key=`. + +##### Optional +* `OTEL_SERVICE_NAME`: Unique identifier for your app/service in telemetry data (defaults to synapseclient). Use a descriptive name so you can easily filter and analyze traces per service. * `OTEL_DEBUG_CONSOLE`: Controls local visibility of telemetry data. Set to 'true' to output trace information to the console, which is useful for development and troubleshooting without an external collector. * `OTEL_SERVICE_INSTANCE_ID`: Distinguishes between multiple instances of the same service (e.g., 'prod', 'development', 'local'). This helps identify which specific deployment or environment generated particular traces. -* `OTEL_EXPORTER_OTLP_HEADERS`: Configures authentication and metadata for telemetry exports. Use this to add API keys, authentication tokens, or custom metadata when sending traces to secured collectors or third-party monitoring services. - #### Enabling OpenTelemetry in your code +You can copy `.env.example` file to `.env` and fill in the values as needed + To enable OpenTelemetry with the Synapse Python client, simply call the `enable_open_telemetry()` method on the Synapse class. Additionally you can access an instance of the OpenTelemetry tracer via the `get_tracer()` call. This will allow you @@ -317,6 +312,10 @@ to create new spans for your code. ```python import synapseclient +from dotenv import load_dotenv + +# load environment variables from .env file +load_dotenv() # Enable OpenTelemetry with default settings synapseclient.Synapse.enable_open_telemetry() diff --git a/setup.cfg b/setup.cfg index e42b15d89..516b6d572 100644 --- a/setup.cfg +++ b/setup.cfg @@ -90,6 +90,7 @@ dev = black pre-commit pandas>=1.5,<3.0 + dotenv tests = pytest~=8.2.0 From 4b26c15adb1b3bd5c9433bd41ee703061c1f9fd6 Mon Sep 17 00:00:00 2001 From: Lingling Peng Date: Tue, 21 Oct 2025 17:16:17 -0400 Subject: [PATCH 2/5] add an additional section; restore section for jaeger --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 54 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a31ea2826..6c3c77588 100644 --- a/README.md +++ b/README.md @@ -280,6 +280,55 @@ OpenTelemetry (OTEL) Read more about OpenTelemetry in Python [here](https://opentelemetry.io/docs/instrumentation/python/) + +### Exporting Synapse Client Traces to Jaeger for developers +The following shows an example of setting up [jaegertracing](https://www.jaegertracing.io/docs/1.50/deployment/#all-in-one) via docker and executing a simple python script that implements the Synapse Python client. + +#### Running the jaeger docker container +Start a docker container with the following options: +``` +docker run --name jaeger \ + -e COLLECTOR_OTLP_ENABLED=true \ + -p 16686:16686 \ + -p 4318:4318 \ + jaegertracing/all-in-one:latest +``` +Explanation of ports: +* `4318` HTTP port for OTLP data collection +* `16686` Jaeger UI for visualizing traces + +Once the docker container is running you can access the Jaeger UI via: `http://localhost:16686` + +#### Environment Variable Configuration + +By default, the OTEL exporter sends trace data to `http://localhost:4318/v1/traces`. You can customize the behavior through environment variables: + +* `OTEL_SERVICE_NAME`: Defines a unique identifier for your application or service in telemetry data (defaults to 'synapseclient'). Set this to a descriptive name that represents your specific implementation, making it easier to filter and analyze traces in your monitoring system. +* `OTEL_EXPORTER_OTLP_ENDPOINT`: Specifies the destination URL for sending telemetry data (defaults to 'http://localhost:4318'). Configure this to direct data to your preferred OpenTelemetry collector or monitoring service. +* `OTEL_DEBUG_CONSOLE`: Controls local visibility of telemetry data. Set to 'true' to output trace information to the console, which is useful for development and troubleshooting without an external collector. +* `OTEL_SERVICE_INSTANCE_ID`: Distinguishes between multiple instances of the same service (e.g., 'prod', 'development', 'local'). This helps identify which specific deployment or environment generated particular traces. +* `OTEL_EXPORTER_OTLP_HEADERS`: Configures authentication and metadata for telemetry exports. Use this to add API keys, authentication tokens, or custom metadata when sending traces to secured collectors or third-party monitoring services. + + +#### Enabling OpenTelemetry in your code +To enable OpenTelemetry with the Synapse Python client, simply call the +`enable_open_telemetry()` method on the Synapse class. Additionally you can access an +instance of the OpenTelemetry tracer via the `get_tracer()` call. This will allow you +to create new spans for your code. + +```python +import synapseclient + +# Enable OpenTelemetry with default settings +synapseclient.Synapse.enable_open_telemetry() +tracer = synapseclient.Synapse.get_tracer() + +# Then create and use the Synapse client as usual +with tracer.start_as_current_span("my_function_span"): + syn = synapseclient.Synapse() + syn.login(authToken='auth_token') +``` + ### Exporting Synapse Client Traces to SigNoz Cloud for developers #### Prerequisites @@ -303,8 +352,6 @@ Explanation of both required and optional environment variables: * `OTEL_SERVICE_INSTANCE_ID`: Distinguishes between multiple instances of the same service (e.g., 'prod', 'development', 'local'). This helps identify which specific deployment or environment generated particular traces. #### Enabling OpenTelemetry in your code -You can copy `.env.example` file to `.env` and fill in the values as needed - To enable OpenTelemetry with the Synapse Python client, simply call the `enable_open_telemetry()` method on the Synapse class. Additionally you can access an instance of the OpenTelemetry tracer via the `get_tracer()` call. This will allow you @@ -314,8 +361,11 @@ to create new spans for your code. import synapseclient from dotenv import load_dotenv -# load environment variables from .env file -load_dotenv() +# Set environment variables +os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://ingest.us.signoz.cloud" +os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = "signoz-ingestion-key=" +os.environ["OTEL_SERVICE_NAME"] = "your-service-name" +os.environ["OTEL_SERVICE_INSTANCE_ID"] = "local" # Enable OpenTelemetry with default settings synapseclient.Synapse.enable_open_telemetry() From f21390ecb2db6257ef1008f7694a985617f240f4 Mon Sep 17 00:00:00 2001 From: Lingling Peng Date: Wed, 22 Oct 2025 10:26:11 -0400 Subject: [PATCH 3/5] revert changes in the .env.example --- .env.example | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.env.example b/.env.example index b02b3acd6..ce96073c2 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,5 @@ ## Here are the environment variables you can set for the Synapse Python client to configure OpenTelemetry tracing and metrics: # You can copy this file to `.env` and fill in the values as needed. -# OTEL_SERVICE_NAME=my-service-using-synapse-python-client -# OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.us.signoz.cloud -# OTEL_SERVICE_INSTANCE_ID=local -# OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key= +# OTEL_EXPORTER_OTLP_ENDPOINT=http://fill-me-in +# OTEL_SERVICE_INSTANCE_ID=local_development_testing +# OTEL_EXPORTER_OTLP_HEADERS=# Authorization From 3a9fded70dfe67f59e42462a2291ca9def47b155 Mon Sep 17 00:00:00 2001 From: Lingling Peng Date: Wed, 22 Oct 2025 10:26:43 -0400 Subject: [PATCH 4/5] revert changes to the .env.example file --- .env.example | 1 + 1 file changed, 1 insertion(+) diff --git a/.env.example b/.env.example index ce96073c2..fe67bd73c 100644 --- a/.env.example +++ b/.env.example @@ -1,5 +1,6 @@ ## Here are the environment variables you can set for the Synapse Python client to configure OpenTelemetry tracing and metrics: # You can copy this file to `.env` and fill in the values as needed. +# OTEL_SERVICE_NAME=my-service-using-synapse-python-client # OTEL_EXPORTER_OTLP_ENDPOINT=http://fill-me-in # OTEL_SERVICE_INSTANCE_ID=local_development_testing # OTEL_EXPORTER_OTLP_HEADERS=# Authorization From 992ef42b1e85ea00390e350586ae0096022eec82 Mon Sep 17 00:00:00 2001 From: Lingling Peng Date: Wed, 22 Oct 2025 10:27:25 -0400 Subject: [PATCH 5/5] revert changes in the setup.cfg --- setup.cfg | 1 - 1 file changed, 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 516b6d572..e42b15d89 100644 --- a/setup.cfg +++ b/setup.cfg @@ -90,7 +90,6 @@ dev = black pre-commit pandas>=1.5,<3.0 - dotenv tests = pytest~=8.2.0