Add a synthetic private probe

What is a private probe?

Use SolarWinds Observability Digital Experience private probes to monitor your internally and externally hosted website or URI entities. Private probes are deployed as a single docker image that can be deployed in a container environment.

The Digital Experience private probe connects to SolarWinds Observability through the Synthetics Collector service which acts as an API Gateway for private probes. The service provides gRPC endpoints for probe auto registration, polling schedules, sending results, and status updates.

The Synthetic collector is publicly reachable from the internet so that private probes can be deployed outside of the SolarWinds Observability infrastructure. Private probes are authenticated in SolarWinds Observability by using the API Token of type Ingestion.

To Deploy your private probe, you must complete the following.

Review the System Requirements to ensure your system meets the required standards.
Create a new ingestion token in SolarWinds Observability and configure it in the private probe.
Configure the private probe with the service URL that corresponds to the data cell of the SolarWinds Observability organization. The connection with SolarWinds Observability is encrypted and minimum TLS 1.2 is required.

Hardware and Software requirements

To deploy a private probe, your system must meet baseline requirements. Each private probe requires the following minimum resources. These values represent the base overhead for running the probe container itself.

Baseline requirements per private probe instance

CPU: 20 mCores
Memory: 100 MiB

These requirements scale depending on the number of parallel checks (checks that run at the same time) you plan to run.

SolarWinds recommends an additional 100 MiB memory allocation for each parallel check execution for the in-memory result buffer for maximum private probe performance. You should monitor your resource usage to make sure you have enough memory to execute the checks on your private probe.

Additional requirements per parallel check execution

For each additional check execution running in parallel, the following resources are required.

CPU: 30 mCores
Memory: 30 MiB
Buffer Memory (recommended): 100 MiB (for in-memory result buffering)

For more information about how checks are counted within SolarWinds Observability Digital Experience, see Subscription.

Requirements example

Consider the following example. You execute 1000 checks every 60 seconds. If your probe location performs 1000 checks every 60 seconds, you can calculate the number of parallel check executions as:

1000/60≈16.61000

This rounds up to 17 parallel check executions. In this scenario, our resources are calculated as follows.

Resource Calculation

CPU:
- Base: 20 mCores
- Per check: 30 mCores × 17 = 510 mCores
- Total: ~530 mCores, rounded up to 1 vCPU
Memory:
- Base: 100 MiB
- Per check: 30 MiB × 17 = 510 MiB
- Buffer: 100 MiB × 17 = 1.7 GiB
- Total: ~2.31 GiB, rounded up to 3 GiB

Summary of Recommended Resources for 17 Parallel Executions:

Resource	Calculation	Recommended Total
CPU	20 + (30 × 17) = 530 mCores	1 vCPU
Memory	100 + (30 × 17) + (100 × 17) = 2.31 GiB	3 GiB

Private probe endpoints

The private probe agent requires access to the following SolarWinds Observability services.

URLs

The following URLs are used by the private probe to retrieve check schedules and submit check results to the Synthetics-Collector service through gRPC protocol.

synthetics.collector.na-01.cloud.solarwinds.com
synthetics.collector.na-02.cloud.solarwinds.com
synthetics.collector.eu-01.cloud.solarwinds.com
synthetics.collector.ap-01.cloud.solarwinds.com

See the endpoint system requirements to determine which endpoint is correct for your organization.

This process uses port 443 and is only an outbound communication.

Additional services

The private probe exposes the following services.

Service	Port	Endpoint	Description
Prometheus	9091	/metrics	It provides access to the private probe metrics. It needs to be exposed in docker. It allows only inbound connections.
Healthcheck	8080	/readyz /livez	Serves the private probe service health status. It needs to be exposed in docker. It allows only inbound connections.

Service

Port

Endpoint

Description

Prometheus

9091

/metrics

It provides access to the private probe metrics. It needs to be exposed in docker. It allows only inbound connections.

Healthcheck

8080

/readyz

/livez

Serves the private probe service health status. It needs to be exposed in docker. It allows only inbound connections.

Download the Docker image

Before installing your private probe, you need to download the Docker image. Download the Docker image https://hub.docker.com/r/solarwinds/synthetics-private-probe.

Create the API token

Create an API ingestion token that will be used to configure your private probe. See API Tokens for instructions.

Configure your private probe

The private probe will attempt to load the configuration file within the Docker container under the specified path at app/config/private-probe.yaml by default (if the file exists).

The file needs to be mounted as a volume in Docker under the specified path.

You can modify the configuration file path by manually setting the PRIVATE_PROBE_CONFIG_FILE environment variable in Docker. See the example configuration file below.

private-probe:
  information:
    local_id: "local-private-probe"
    name: "My local private probe"
  options:
    synthetics_collector_url: "synthetics.collector.xx.cloud.solarwinds.com:0101"
    api_token: "INGESTION_TOKEN"
  log_level: "INFO"
    fetch_periodic_schedule_interval: 60s
    fetch_one_time_schedule_interval: 60s
    resend_results_interval: 60s
    results_buffer_limit: 10000
    api_client_timeout: 30s
    executor_soft_timeout_extension: 5s
    external_executor_hard_timeout: 60s
    transaction_executor_hard_timeout: 65s
    binary_size_limit_mb: 1

Configuration options loaded from the .yaml file can be overwritten by environment variables. If there are no configuration parameters explicitly set, the default values are used.

There are four required configuration options that allow the probe to connect to Synthetics Collector and automatically register the probe in SolarWinds Observability. LOCAL_ID plays a special management role as it defines identity of the probe container instance from the SWO point of view. Here are some implications coming from this option:

Providing new LOCAL_ID will automatically register a new probe in SolarWinds Observability.
Providing the same LOCAL_ID when redeploying the container keeps its identity the same meaning the same checks will execute like they did with the previous deployment.
Multiple containers running with the same LOCAL_ID are considered a single instance of private probe by SolarWinds Observability. The multiple containers will execute the same checks on the same schedule.

The following private probe configuration options are available.

Environment Variable Name	Required	Default value	Description
`SYNTHETICS_COLLECTOR_URL`	Yes		Specifies the URL of the Synthetics Collector service where the probe will connect. See private probe endpoints above for a list of URLs.
`API_TOKEN`	Yes		Specifies the ingestion token used to authenticate the probe with Synthetics Collector.
`LOCAL_ID`	Yes		User defined unique identifier for the private probe which allows the probe to bind a running container instance in SolarWinds Observability.
`NAME`	Yes		User defined name for the probe visible in SolarWinds Observability.
`LOG_LEVEL`	No	INFO	Specifies the verbosity level of log messages generated by the probe (`DEBUG/INFO/WARN/ERROR`).
`FETCH_PERIODIC_SCHEDULE_INTERVAL`	No	60 seconds (s)	Specifies the interval at which the probe fetches the periodic schedule from the Synthetics Collector.
`FETCH_ONE_TIME_SCHEDULE_INTERVAL`	No	30 seconds (s)	Specifies the interval at which the probe fetches the one-time schedule from the Synthetics Collector.
`RESEND_RESULTS_INTERVAL`	No	60 seconds (s)	Specifies the interval at which the probe will try to resend results that failed to be sent by the Synthetics Collector.
`RESULTS_BUFFER_LIMIT`	No	10000	Specifies the maximum number of results that are stored for send attempts.
`API_CLIENT_TIMEOUT`	No	30 seconds (s)	Specifies timeout for communication with Synthetics Collector.
`EXTERNAL_EXECUTOR_HARD_TIMEOUT`	No	61 seconds (s)	Specifies the hard timeout for the check executor.
`TRANSACTION_EXECUTOR_HARD_TIMEOUT`	No	65 seconds (s)	Specifies the hard timeout for the transaction executor.
`EXECUTOR_SOFT_TIMEOUT_EXTENSION`	No	5 seconds (s)	Specifies the soft timeout for the check executor. (This value is added to the executor hard timeout and to the transaction executor hard timeout).
`BINARY_SIZE_LIMIT_MB`	No	1	Specifies the binary output limit for the transaction executor in megabytes (mb).

Deploy your private probe

The Digital Experience private probe is a single docker image that can be deployed in a container environment.

Docker Deployment

Execute the private probe on Docker with the environment variables listed in Configure your private probe. See the example below.

docker run -d \
-e SYNTHETICS_COLLECTOR_URL='synthetics.collector.xx-xx.cloud.solarwinds.com' \
-e API_TOKEN='INGESTION_TOKEN' \
-e LOG_LEVEL='INFO' \
-e LOCAL_ID='local-private-probe' \
-e NAME='My local private probe' \
solarwinds/synthetics-private-probe:latest

Docker Deployment with config file

Execute the private probe on Docker with a configuration file. In the following example, the environment variable specifies the custom configuration file path to private-probe.yaml. See the example below.

docker run -d -e

PRIVATE_PROBE_CONFIG_FILE=private-probe.yaml

-v ./config-to-mount/private-probe.yaml:/app/private-probe.yaml solarwinds/synthetics-private-probe:latest

See the Example configuration file below.

private-probe:
  information:
    local_id: "local-private-probe"
    name: "My local private probe"
  options:
    synthetics_collector_url: "synthetics.collector.xx-xx.cloud.solarwinds.com"
    api_token: "INGESTION_TOKEN"
    log_level: "INFO"

Docker Deployment with compose file

See the Example Docker compose file below.

name: local-private-probe
  services:
    dem-private-probe:
    image: solarwinds/synthetics-private-probe:latest
  environment:
    SYNTHETICS_COLLECTOR_URL: "synthetics.collector.xx-xx.cloud.solarwinds.com"
    API_TOKEN: "INGESTION_TOKEN"
    LOCAL_ID: "local-private-probe"
    NAME: "My local private probe"
    LOG_LEVEL: "INFO"

Execute the compose file as follows.

docker compose -f private-probe-compose.yml up -d

Troubleshoot the private probe

If you are encountering any issues with your private probe, you can take the following troubleshooting steps.

Review DEBUG logs

Set the log level to DEBUG within your PRIVATE_PROBE_CONFIG_FILE.
Check the following Docker Container Logs for these key metrics.

probeID is reviewable in the Container logs after the private probe starts. traceID is reviewable in the Container logs if an error occurs.

Example: probeID

{"time":"2025-08-12T13:25:18.402069508Z","level":"INFO","msg":"Probe registered","probeID":"06ddbb70-0048-4642-aad8-f26ca83d0948"}

Example: traceID

{"time":"2025-08-12T13:25:18.516435626Z","level":"ERROR","msg":"something went wrong","error":"rpc error: code = NotFound desc = not found, trace id: ec03bf06cb97904bd0ce4bbda9946051"}

Monitor the private probe with SolarWinds Observability

For private probes deployed in Cloud environments:

Use SolarWinds Observability to monitor your Cloud Providers infrastructure and view useful metrics generated by the Cloud Provider. See infrastructure monitoring for instructions regarding your Cloud Provider.

For private probes deployed in Kubernetes environments:

Use SolarWinds Observability to monitor your Kubernetes cluster to view basic METRICS and LOGS. See Kubernetes monitoring.

Search SolarWinds Support