Skip to content

Troubleshooting & FAQ#

Common issues and their solutions when working with the Virtual Parameter Service.

Common Issues#

VPS container starts but no sessions are detected#

Checklist
  1. Is ADS running? Ensure ADS is active and streaming live data.
  2. Is the Bridge Service running? Verify the Bridge Service container is healthy: docker ps.
  3. Is the Bridge Service configured correctly? See its own configuration guide for enabling it and setting BrokerUrl.
  4. Is the DataSource correct? The VPS's DataSource (AppConfig.json) must match the DataSource name Bridge Service publishes under.
  5. Is Kafka reachable? The BrokerUrl in AppConfig.json must point to a valid, running Kafka broker — the same one Bridge Service is configured to publish to.
  6. Do StreamCreationStrategy and PartitionMappings match Bridge Service? If StreamApiConfig.StreamCreationStrategy doesn't match Bridge Service's setting, the VPS is looking for data in the wrong place (topics vs. partitions). If it's 1 (partition-based), PartitionMappings must match Bridge Service's mapping too — it's ignored for 2 (topic-based).

Kafka is not initialised in time before the Bridge Service#

This is a known issue when starting the full Docker Compose stack. The Bridge Service may start before Kafka is fully ready.

Solution

Restart the bridge-service and virtual-parameter-service containers manually:

docker restart bridge-service
docker restart virtual-parameter-service

Alternatively, add health checks and depends_on conditions to your docker-compose.yaml.

Prometheus target shows DOWN#

Checklist
  1. Is prometheus.yml configured correctly? The target must be your machine's IPv4 address, not localhost.
  2. Is the VPS running and healthy? Check docker ps for the container status.
  3. Is port 10010 exposed? Confirm the port mapping with docker ps or test with curl http://YOUR_IP:10010/metrics.
  4. Firewall? Ensure port 10010 is not blocked by a firewall rule.

Metrics endpoint returns an error when running manually#

The Prometheus HTTP listener requires Administrator privileges when running outside Docker.

Solution

Run MA.DataPlatforms.VirtualParameterService.Host.exe as Administrator.

Virtual parameter definitions are failing to build#

Check the vps_virtual_parameter_definition_failed_counter metric for the count of failures.

Possible causes
  • Missing source parameters — The FDL expression references parameters that are not present in the session.
  • Invalid FDL expressions — The expression syntax is incorrect or unsupported.
  • Dependency resolution failure — A virtual parameter depends on another virtual that has not yet been defined.

Check the service logs (set MinimumLevel to Debug in the Serilog config) for detailed error messages about which definitions failed and why.

Incomplete virtual parameter definitions (gauge is non-zero)#

The vps_virtual_parameter_definition_incomplete_gauge indicates virtual definitions waiting for their source dependencies to be defined.

Explanation

This is normal during session startup — virtual parameters that depend on other virtuals may be temporarily incomplete until all definitions are received. The gauge should return to 0 once all configuration packets have been processed.

If it remains non-zero indefinitely, check that all required source parameter definitions are being published in the session's configuration packets.

A virtual parameter's values stop appearing after a source replays old data (Snapshot mode)#

Explanation

In Snapshot calculation mode, a source sample older than the latest value already recorded for that parameter is rejected rather than applied retroactively — this is expected behaviour, not a bug. If your source can redeliver historical or out-of-order samples (e.g. replaying a recorded session), use CalculationMode: "Default" instead. See Calculation Modes.

Log file is not being created#

Checklist
  1. Does the Serilog config override the path? The Serilog section in AppConfig.json takes precedence over -l arguments and LOG_FILE_PATH environment variables.
  2. Is the path valid? The log file must end in .txt. If an invalid extension is provided, the service reverts to the default path.
  3. Does the directory exist? The directory must exist — the service does not create intermediate directories.
  4. Permissions? The service process must have write access to the target directory.

FAQ#

Can I run multiple VPS instances for different data sources?#

Yes. Each VPS instance supports a single DataSource. To process multiple data sources, deploy separate instances with different AppConfig.json files, each specifying a different DataSource value. Ensure each instance uses a unique StreamApiPort and METRIC_PORT.

Which calculation mode should I use?#

Use Snapshot for live streaming — it keeps memory flat over long-running sessions and keeps producing values even when a source ticks slowly. Use Default for replayed/recorded sessions, or any source that can deliver samples out of order, since Snapshot rejects out-of-order samples. See Calculation Modes for the full comparison.

Does the VPS process historical sessions?#

No. The VPS only processes live sessions. Historical sessions and sessions of type VirtualSession are automatically filtered out to avoid reprocessing its own output.

What happens if the VPS goes down during a live session?#

The VPS does not persist state between restarts. If the service restarts, it will detect any active live sessions and begin processing them from that point forward. Data generated during the downtime will not be retroactively computed.

Can I change the buffering window while the service is running?#

No. Configuration is loaded at startup. To change BufferingWindowLengthInMs or SlidingWindowPercentage, update AppConfig.json and restart the service.

What Kafka topics does the VPS use?#

The VPS uses the Stream API to manage topic creation and data flow. Topics are created automatically based on the configured StreamCreationStrategy. You do not need to manually create Kafka topics.

How do I verify that virtual data is being written correctly?#

  1. Check metrics — Ensure vps_virtual_parameter_packet_info_packager_packaged_counter is incrementing.