Skip to content

Data planes

A data plane is a small DV Forge service that you run inside your own network, on-prem or in your own cloud account. CI uploads go to it instead of to DV Forge. It keeps the raw simulation logs in your storage, analyzes failures locally, and sends DV Forge only structured, redacted results. This page is for the administrators who decide whether to use one, install it, and keep it healthy.

Why use a data plane

Without a data plane, a project uploads straight to DV Forge, and DV Forge stores the logs. That's the quickest way to start. With a data plane:

  • Raw logs stay in your network. They're stored only in the data plane's storage: a local disk or an S3-compatible bucket you own.
  • Failures are analyzed where the logs are. The data plane parses each failing job's log, applies your redaction rules, and forwards only the result.
  • Connections are outbound only. The data plane connects out to DV Forge over HTTPS. You don't open any inbound firewall ports to the internet. It sends heartbeats and asks DV Forge for work, such as "send the log for job X, because a user opened it".
  • Uploads survive outages. If DV Forge is unreachable, the data plane queues results on disk and forwards them later.
flowchart LR
    subgraph net["Your network"]
        CI["CI: dvforge upload"] -->|"results + logs"| DP["Data plane<br/>logs · parsing · redaction"]
        DP --- ST[("Log storage")]
    end
    DP -->|"outbound HTTPS only:<br/>results, redacted analyses"| DV["DV Forge"]

What leaves your network

Sent to DV Forge Never sent
Job metadata: test name, status, seed, component, simulator, build target, configuration, plusargs, host, runtime, cycles, exit code, and the log's SHA-256 hash Raw logs. They stay in the data plane's storage.
For each failing job, the failure analysis after redaction: headline, error line, signature title, parsed messages, and an excerpt capped at 16 KiB by default RTL, repositories, and design files
A job's one-line failure message, after redaction Anything in bulk: there is no export path
A full log, only when a user opens it in the log viewer. It passes through DV Forge to the user's browser and isn't stored. Queued uploads at rest. They stay on the data plane's disk until delivered.
Heartbeats: the data plane's version and queue health (counts and the last error)

Redaction covers the analysis, not the metadata

Your redaction patterns apply to the failure analysis and the job's failure message. Job metadata such as test names, plusargs, configuration, and host names is forwarded as your JUnit reports it. See Redaction on a data plane.

Before you begin

  • Roles. Registering and revoking data planes needs the org_admin role. Binding a project needs project_admin or higher (roles apply to every project in the organization). See Projects, roles and tokens.
  • The data plane software. Your DV Forge contact provides it as a container image or as a Python package (Python 3.11 or later).
  • A host in your network that your CI machines can reach on port 8100 (or a port you choose), and that can make outbound HTTPS connections to https://api.daruur.cloud.
  • Persistent storage for logs and the outage queue. Logs can go to an S3-compatible bucket instead, but the queue always needs a local disk.

Set up a data plane

1. Register it

  1. In the app, select Data planes in the sidebar.
  2. Under Manage, type a name in Register a data plane, for example austin-farm or cloud-west.
  3. Select Register.
  4. Copy the key that appears. It starts with dvp_, and it is shown only once: "copy it now, it won’t be shown again". Store it in your secret manager, then select I've stored it.

The data plane appears in the Registered table as offline until it sends its first heartbeat. Only signed-in people manage data planes; project tokens can't create, list, or revoke them.

2. Install and start it

The data plane is configured entirely through environment variables. Two are required:

Variable Value
DVFORGE_DP_CONTROL_PLANE_URL https://api.daruur.cloud
DVFORGE_DP_KEY The dvp_ key from step 1
docker run -d --name dvforge-dataplane --restart unless-stopped \
  -p 8100:8100 \
  -v dvforge-data:/data \
  -e DVFORGE_DP_CONTROL_PLANE_URL=https://api.daruur.cloud \
  -e DVFORGE_DP_KEY=dvp_... \
  <the data plane image from your DV Forge contact>

The image runs as a non-root user, listens on port 8100, and keeps logs in /data/blobs and the outage queue in /data/spool. Mount /data on persistent storage. The image includes a health check against /healthz.

python3.11 -m venv /opt/dvforge-dataplane
/opt/dvforge-dataplane/bin/pip install /path/to/the-data-plane-package
export DVFORGE_DP_CONTROL_PLANE_URL=https://api.daruur.cloud
export DVFORGE_DP_KEY=dvp_...
export DVFORGE_DP_BLOB_DIR=/srv/dvforge/blobs
/opt/dvforge-dataplane/bin/dvforge-dataplane

The package installs the dvforge-dataplane command. It also reads a .env file in its working directory. Run it under your service manager so it restarts after a reboot.

If a setting is missing or invalid, the data plane prints dvforge-dataplane: invalid configuration: followed by each offending variable, and exits with code 2. dvforge-dataplane --version prints its version.

Plain HTTP on the CI side

The data plane serves HTTP. If your CI machines reach it across a network you don't trust, put a TLS-terminating proxy or load balancer in front of it. Its own connection to DV Forge always uses the HTTPS URL you configure.

Within one heartbeat (30 seconds by default), the data plane shows as online on the Data planes page.

3. Bind projects to it

A project uses a data plane only once it's bound to it.

  1. Select the project in the project switcher.
  2. Open Data planes in the sidebar.
  3. Under Manage, in Where project keeps its raw logs, choose Data plane: name. The change takes effect immediately.

Repeat for each project. One data plane can serve several projects in the same organization.

Switch the upload URL at the same time

From the moment a project is bound, DV Forge refuses direct uploads for it ("this project ingests through its data plane; point the uploader at it") and refuses the paste form. A data plane, in turn, refuses projects that aren't bound to it. Bind the project and update DVFORGE_URL in CI together, between two nightly runs.

4. Point the CLI at it

In your CI, set DVFORGE_URL to the data plane's address. Keep the same project token; the data plane passes it on to DV Forge, which checks it.

export DVFORGE_URL=http://dvforge-dp.example.internal:8100
export DVFORGE_TOKEN=dvf_...      # the project's usual token
dvforge upload --name "nightly $BUILD_ID" --external-id "$BUILD_ID" \
  --junit out/results.xml --logs 'out/logs/**/*.log' --only-failing-logs

Nothing else in the command changes. See CI integration.

Configuration reference

Every setting is an environment variable starting with DVFORGE_DP_.

Variable Default Meaning
DVFORGE_DP_CONTROL_PLANE_URL required DV Forge's API URL: https://api.daruur.cloud.
DVFORGE_DP_KEY required This data plane's dvp_ key. Never logged.
DVFORGE_DP_BLOB_BACKEND local Where logs are stored: local (disk) or s3 (AWS S3 or any S3-compatible store).
DVFORGE_DP_BLOB_DIR ./data/blobs Log directory for local (/data/blobs in the container).
DVFORGE_DP_S3_BUCKET none Bucket for s3. Required with s3; created if it doesn't exist.
DVFORGE_DP_S3_ENDPOINT_URL none Endpoint of an S3-compatible store. Leave empty for AWS S3.
DVFORGE_DP_S3_REGION none S3 region.
DVFORGE_DP_REDACT_PATTERNS [] JSON array of regular expressions. Every match in a failure analysis or a job's failure message becomes [redacted] before forwarding. Example: '["tb_top(\\.\\w+)+", "0x[0-9a-fA-F]{8,}"]'.
DVFORGE_DP_MAX_EXCERPT_CHARS 16384 Maximum excerpt size forwarded per failure, up to 65536. 0 forwards no log lines.
DVFORGE_DP_EXCERPT_CONTEXT_LINES 25 Lines kept before and after the failure in the excerpt.
DVFORGE_DP_HEARTBEAT_SEC 30 Seconds between heartbeats. Keep it well under 90, or the data plane will show as offline.
DVFORGE_DP_CLAIM_WAIT_SEC 20 How long each request for work waits for a task, in seconds (at most 25).
DVFORGE_DP_TOKEN_CACHE_SEC 60 How long the data plane remembers that a CI token is valid. 0 checks every request.
DVFORGE_DP_TOKEN_GRACE_SEC 21600 (6 hours) While DV Forge is unreachable, how long a token checked successfully before keeps working. 0 disables.
DVFORGE_DP_SPOOL_DIR spool next to the blob directory The outage queue (/data/spool in the container). Keep it on persistent storage, even with s3 logs.
DVFORGE_DP_SPOOL_MAX_BYTES 1073741824 (1 GiB) Size cap for queued uploads. 0 disables queuing.
DVFORGE_DP_SPOOL_MAX_FILES 10000 Entry cap for queued uploads. 0 disables queuing.
DVFORGE_DP_SPOOL_DEAD_MAX_BYTES 268435456 (256 MiB) Size cap for dead letters; the oldest are removed first.
DVFORGE_DP_SPOOL_DEAD_MAX_FILES 1000 Count cap for dead letters.
DVFORGE_DP_SPOOL_DEAD_MAX_AGE_DAYS 30 Dead letters older than this are deleted.
DVFORGE_DP_MAX_UPLOAD_BYTES 67108864 (64 MiB) Largest log upload or job batch request accepted.
DVFORGE_DP_MAX_LOG_BYTES 268435456 (256 MiB) Largest log accepted, uncompressed.
DVFORGE_DP_HOST, DVFORGE_DP_PORT 0.0.0.0, 8100 Listen address and port.
DVFORGE_DP_LOG_LEVEL info debug, info, warning, or error.

Monitoring

In the app

The Data planes page lists every data plane in your organizations under Registered:

Column What it shows
Name The name you registered.
Status online (a heartbeat in the last 90 seconds), offline, or revoked.
Version The data plane software version it last reported.
Spool The health of its outage queue (see below).
Projects Projects bound to it.
Last seen Its last heartbeat or request for work, or "never".
Key The start of its key, dvp_<prefix>_…, so you can tell keys apart.

On the data plane

GET /healthz on the data plane returns its own view as JSON: status, version, org, bound projects, last_heartbeat_at, control_plane_reachable, last_error, counts of log requests served and refused, and spool health. Use it for your own monitoring or load-balancer checks.

curl -s http://dvforge-dp.example.internal:8100/healthz

The outage queue (spool)

If the data plane can't reach DV Forge while CI is uploading (a network failure, a timeout, or HTTP 502, 503, or 504), it doesn't fail the upload:

  • Logs are stored locally as usual. They never needed DV Forge.
  • Job batches and the completion of a regression are written to the spool and acknowledged to the CLI as queued. The CLI exits 0 and says the upload was "spooled on the data plane".
  • Opening a regression can't be queued, because the CLI needs the regression id DV Forge returns. The data plane answers "try again later", the CLI retries, and if DV Forge stays unreachable the CLI exits 4.

A background loop forwards the queue oldest first, as soon as DV Forge answers again. Batches for one regression are never reordered, and the completion always goes last. Each entry is written to disk safely, so the queue survives crashes and restarts, and an entry sent twice is recognized by DV Forge and not counted twice.

The queue holds exactly what would have been forwarded: the analyzed, redacted batch, never a raw log. It also holds the uploader's token, because DV Forge checks it again on delivery. Files are readable only by the data plane's user and are deleted once delivered.

Spool health in the app

Indicator Meaning
empty Nothing waiting.
N waiting Uploads queued for DV Forge. Hover to see the last error. They drain by themselves once the data plane can reach DV Forge.
N dead letter(s) Uploads DV Forge refused for good. Hover to see the last reason.
— The data plane hasn't reported queue health.

Dead letters are queued uploads that DV Forge rejected permanently: for example, the token was revoked, the regression was deleted, or the request was invalid. They're not retried. The data plane moves them to the dead directory inside the spool, removes the token from them, and deletes them after 30 days by default. To recover the results, fix the cause (such as the token) and rerun the CI upload. It's safe to repeat.

When the queue reaches DVFORGE_DP_SPOOL_MAX_BYTES or DVFORGE_DP_SPOOL_MAX_FILES, the data plane stops accepting batches until it drains; the CLI retries and then exits 4.

When something is offline

Situation Uploads Log viewer
DV Forge is unreachable from the data plane Logs are stored; batches and completions are queued and forwarded later. New regressions can't be opened until DV Forge is back (CLI exit 4). CI tokens checked in the last 6 hours keep working. Unavailable for this data plane's logs.
The data plane is down or unreachable from CI Fail after the CLI's retries (exit 4). Rerun once it's back. Shows "This log lives in your data plane, which didn't answer."

Analyses, signatures, and triage in DV Forge keep working in every case: they don't need the raw logs.

Unbinding a project

To move a project back to direct uploads, choose Embedded (DV Forge control plane — dev and demos) in Where project keeps its raw logs, then set DVFORGE_URL back to https://api.daruur.cloud in CI. Logs uploaded while the project was bound stay in the data plane, and the log viewer keeps fetching them from there.

Revoking a data plane

  1. On the Data planes page, under Manage, select Revoke name.
  2. Read the warning: "Its key stops working immediately", and any bound projects "will stop ingesting until you bind them to another data plane".
  3. Select Revoke.

After revoking:

  • The data plane can no longer send heartbeats, forward uploads, or answer log requests. It shows as revoked.
  • Projects still bound to it can't upload anywhere until you bind them to another data plane or back to embedded. The binding list shows the revoked data plane as "revoked — ingest blocked; choose another".
  • Logs stored in the revoked data plane can't be opened from DV Forge anymore, even if the service keeps running. Analyses and signatures are unaffected.

There is no key rotation

A data plane's key can't be replaced. Replacing it means registering a new data plane, binding the projects to it, and revoking the old one. The log viewer finds each log through the data plane that stored it, so logs stored under the old registration become unviewable after the revoke. Plan replacements accordingly, and treat the key like any other long-lived secret.

Security notes

  • The data plane never checks CI tokens itself. It asks DV Forge, caches the answer for 60 seconds by default, and refuses tokens that can't write to the project, and projects that aren't bound to it.
  • DV Forge can ask the data plane for one thing only: the beginning of a stored log (up to 4 Mi characters), when a user opens it. The data plane refuses any other kind of request, so DV Forge can't make it do anything else inside your network.
  • The data plane contains the log parsing library and nothing else from DV Forge.