DCA Client¶

Experimental

DCA(DataKit Control App) is a web-based management system for centralized DataKit administration. Utilizing a B/S architecture and WebSocket bidirectional communication protocol, it enables unified management of DataKit, such as DataKit list view, runtime info, configuration file management and Pipeline management.

DCA network topology model explained:

flowchart LR;

dca_server(DCA Server);
dca_web(DCA Web);
dk_upgrader1("Upgrade Manager");

dk1(DataKit);

k8s_dk1(DataKit);

brand_name("TrueWatch");

subgraph HOST DataKit
    direction TB;
    dk_upgrader1 --> dk1;         
end

subgraph "Kubernetes DataKit"
 k8s_dk1
end

dk1 -..-> |upload data|brand_name;
k8s_dk1 -..-> |upload data|brand_name;

dca_server <---> |websocket| dk_upgrader1 & k8s_dk1
dca_web -- HTTP --- dca_server;

dca_server -.-> |login/auth| brand_name;

DCA Web Service¶

For automated batch management, enable OpenAPI. Browser login and member permissions retain their existing behavior.

The DCA web service currently supports deployment via container images only, which can be implemented through either Docker or Kubernetes.

docker pull pubrepo.truewatch.com/truewatch/dca:0.5.0

docker run -d --name dca -p 8000:80 pubrepo.truewatch.com/truewatch/dca

$ kubectl apply -f dca.yaml
$ kubectl get pod -n datakit

Environment Variable Configuration¶

By default, DCA will adopt the default configuration of the system. If you need to customize the configuration, you can modify it by injecting environment variables. The following environment variables are currently supported:

Example:

docker run -d --name dca -p 8000:80 -e DCA_LOG_PATH=stdout -e DCA_LOG_LEVEL=info pubrepo.truewatch.com/truewatch/dca

Login and help URLs for private deployments¶

Configure separate addresses for in-cluster requests and browser navigation. DCA_CONSOLE_API_URL is used by the DCA container and may point to a Kubernetes Service. DCA_CONSOLE_WEB_URL must be reachable from the browser. Set the full DCA_LOGIN_URL when a separate login entry point is needed.

These environment variables work with TrueWatch. Restart the DCA container after changing them:

env:
  - name: DCA_CONSOLE_API_URL
    value: "http://console-api.namespace.svc:5000"
  - name: DCA_CONSOLE_WEB_URL
    value: "https://console.customer.example"
  - name: DCA_LOGIN_URL
    value: "https://console.customer.example/integration/dca"
  - name: DCA_DOC_URL
    value: "https://docs.customer.example"

Only HTTP/HTTPS URLs are supported. The documentation service must provide matching paths, such as /datakit/dca and /integrations/cpu/. This setting does not download or deploy documentation. When unset, each brand uses its default documentation domain.

Node address¶

DataKit AIX Host Management¶

Host management shows DataKit AIX when the workspace has unexpired AIX hosts. Compatible agents and datakitaix-upgrader support main-configuration editing, explicit restart, and upgrades. Restart after saving to apply changes; confirm an upgrade from the host status and version.

OpenAPI Automation¶

OpenAPI lets scripts and automation systems manage DataKit instances connected to this DCA. A separate deployment credential grants API management of all workspaces in this DCA instance. Browser login continues to use existing SSO and member permissions.

Enable and Configure¶

Use DCA 0.5.0 or later with matching DataKit and dk_upgrader updates, generate a separate random credential, and mount a persistent database:

export DCA_OPENAPI_TOKEN="$(openssl rand -hex 32)"

DCA_IMAGE="pubrepo.truewatch.com/truewatch/dca:0.5.0"

docker run -d --name dca -p 8000:80 \
  -v dca-data:/var/lib/dca \
  -e DCA_DB_PATH=/var/lib/dca/dca.sqlite \
  -e DCA_OPENAPI_TOKEN \
  "$DCA_IMAGE"

DCA_OPENAPI_TOKEN must contain 32–512 non-whitespace characters. The example generates 64 random hexadecimal characters; use a different credential for each customer deployment. Leaving the variable unset disables OpenAPI. DCA_DB_PATH must name a real database file in an existing directory, rather than the default in-memory database or a SQLite URI.

For Kubernetes, store the credential in a Secret, inject it through secretKeyRef, and persist the database directory with a PVC. The task executor supports a single DCA instance; do not share one task database between replicas. The database contains configuration bodies, so protect the volume and backups as sensitive configuration.

The container example exposes a local HTTP port. Configure DCA TLS or a trusted HTTPS reverse proxy for external API access. Browser login for other sites and private deployments still uses the Console URLs in Node address. OpenAPI validates the deployment credential locally and does not accept a platform API Key or browser Cookie in its place.

Remove the former DCA_OPENAPI_URL authentication setting and configure DCA_OPENAPI_TOKEN instead. Restart DCA after rotating the credential; the old credential can no longer submit requests, and interrupted targets are marked unconfirmed. Pending targets are paused after restart; verify node state, then use the new credential to call resume. Credentials are not stored in tasks or forwarded to DKs. Do not put credentials in URLs. API operations using this shared credential are attributed to deployment, rather than individual members.

Authentication and Workspace Discovery¶

Send Authorization: Bearer <DCA_OPENAPI_TOKEN> with every request. Discover workspace UUIDs and host IDs directly:

export DCA_URL="https://dca.example.com"
curl -sS -H "Authorization: Bearer $DCA_OPENAPI_TOKEN" \
  "$DCA_URL/openapi/v1/workspaces"
curl -sS -H "Authorization: Bearer $DCA_OPENAPI_TOKEN" \
  "$DCA_URL/openapi/v1/hosts"

The workspace response contains content: [{"workspace_uuid":"wksp_xxx","host_count":3}]. It lists only workspaces represented in this DCA's node inventory. The host response provides the host_id values used in tasks. List endpoints support limit (1–200, default 100) and offset (default 0).

When exactly one workspace is connected, other endpoints select it automatically. With multiple workspaces, send X-Workspace-Uuid: <workspace_uuid> to select one; omission returns HTTP 400. Hosts, configurations and tasks are scoped to the selected workspace, and a task cannot mix targets from different workspaces. An empty inventory returns []; an explicit workspace header can still select a known workspace's historical tasks.

Endpoints¶

All paths below use the /openapi/v1 prefix. Responses contain success/code/content/errorCode/message and use HTTP status codes.

Batch Configuration Example¶

Replace placeholders with the discovered workspace UUID and host_id values. This example creates the same CPU configuration on two hosts:

REQUEST_ID="$(openssl rand -hex 16)"
curl -sS -X POST "$DCA_URL/openapi/v1/tasks" \
  -H "Authorization: Bearer $DCA_OPENAPI_TOKEN" \
  -H "X-Workspace-Uuid: wksp_xxx" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "operation": "create",
  "input": "cpu",
  "file_name": "automation.conf",
  "content": "[[inputs.cpu]]\n  percpu = false\n",
  "apply": "save",
  "targets": [{"host_id": "<host-1>"}, {"host_id": "<host-2>"}]
}
JSON

Task submissions require an Idempotency-Key of 1–128 characters. In the same workspace, the same key and request return the original task; a different request with that key returns HTTP 409. Reuse the original key after a timeout to avoid duplicate tasks. The initial response is HTTP 202 with a task ID. Tasks are persisted before background execution and continue after the HTTP client disconnects.

A task accepts 1–5000 explicit targets. input and file_name must be names without directory components. Files are written to conf.d/<input>/<file_name> and content is limited to 1 MiB. This API cannot modify the main DK configuration, Pipelines or arbitrary host files.

Before updating or deleting, read each host's current configuration and revision. Set operation to update or delete and include that host's revision in each targets entry; omit content for deletion. Updates replace the entire file. Creation never overwrites an existing file. Missing files or changed revisions fail only the affected target. Updates and deletions first back up the original file to the DK's data/dca/config-backups/ directory with 0600 permissions; automatic rollback and backup cleanup are not provided.

Use apply to choose how changes take effect:

• save: save or delete the file without changing the running collector.
• reload: reload collectors within the existing DK process after a successful file operation.
• restart: ask the dk_upgrader to restart the DK process and verify its start time and online status.

For a standalone batch reload or restart, send only operation: "reload"/"restart" and targets, without configuration content or apply. Both DK and dk_upgrader must support the protocol; older versions do not receive an unsafe fallback. Container nodes are read-only. Offline or busy targets fail individually.

Batch SNMP Profiles¶

Use the same task endpoint with resource: "snmp_profile" and YAML content:

{
  "resource": "snmp_profile",
  "operation": "create",
  "input": "snmp",
  "file_name": "vendor-router.yaml",
  "content": "extends: [generic-router.yaml]\nsysobjectid: '1.3.6.1.4.1.12345.*'\ndevice: {vendor: custom}\n",
  "apply": "save",
  "targets": [{"host_id": "<host-1>"}]
}

Replace the example sysObjectID with actual device rules. Only custom YAML files under conf.d/snmp/extra_profiles/ can be mutated; built-in files are read-only. Read a built-in template to create custom copies in a batch. Updates and deletions require each target's revision. Each DK validates YAML, inheritance and deletion dependencies. Validation requests contain operation/file_name/content; omit content when validating deletion. Deploy dependency files in earlier batches. Updates and deletions back up files to data/dca/snmp-profile-backups/. Missing dependencies, referenced profiles or unsupported older DKs cause the target operation to fail.

Results and Recovery¶

Query /tasks/{task_id} for progress and /tasks/{task_id}/targets for per-host config_status/apply_status. Task states are active/paused/completed; completed means all targets have finished, not that every target succeeded. Target states are queued/running/succeeded/failed/unconfirmed.

All tasks share five concurrent execution slots and serialize operations on the same host within a workspace. At most 100 unfinished tasks are accepted. A failed target does not stop other hosts or later tasks. Timeouts and lost connections with uncertain outcomes are recorded as unconfirmed and never retried automatically. After a DCA restart, previously running targets require confirmation and targets not yet dispatched are paused. Verify node state before resuming; completed targets are not executed again.

HTTP 401 indicates an invalid credential, 400 invalid parameters or workspace selection, 404 a resource absent from the selected workspace, 409 an idempotency conflict, and 503 an unavailable task queue. Per-host file conflicts are recorded in target results. Task queries return neither configuration bodies nor credentials.

DataKit config¶

DK_DCA_ENABLE=on DK_DCA_WEBSOCKET_SERVER="ws://127.0.0.1:8000/ws" DK_DATAWAY=https://openway.truewatch.com?token=<TOKEN> bash -c "$(curl -L https://static.truewatch.com/datakit-v2/install.sh)"

[dca]
    # Open
    enable = true

    # websocket server address
    websocket_server = "ws://<dca_server_address>/ws"

DCA management¶

Login to DCA¶

After the DCA is enabled and installed, you can access it by entering the address localhost:8000 in your browser. When you visit it for the first time, the page will redirect you to a login transition page. After clicking the "Go Now" button at the bottom of the page, you will be guided to the TrueWatch. Then, follow the instructions on the page to configure the DCA address. Once the configuration is completed, you will be able to directly access the DCA platform through the TrueWatch platform without logging in.

View DataKit list¶

After logging in to DCA, you can select the workspace in the upper left corner to manage its corresponding DataKit and collector, which supports quick filtering of host names to be viewed and managed by searching keywords.

The host list supports ascending or descending sorting by host name, last update time, or registration order. The default is ascending registration ID. Sorting applies to all matching search and filter results before pagination, with registration ID breaking ties. Changing sorting returns to page one and clears bulk selection. Manual and automatic refresh retain the current page and sorting.

Hosts remotely managed through DCA are divided into three states:

• running: indicating that the data report is normal, you can view the operation of DataKit and configure the collector through DCA;
• offline: It means that the DataKit is off line.
• stopped: It means that the DataKit is stopped.
• upgrading: It means that the DataKit is upgrading.
• restarting: It means that the DataKit is restarting.

By default, you can only view information of the DataKit in the current workspace. If you need to manage DataKit, such as upgrading it, creating, deleting, or modifying DataKit collector config file, pipelines, you need to grant current user DCA configuration management permission. Please refer to role management for specific settings.

View How DataKit is Running¶

After logging in to DCA, select a workspace to view the hostname and IP information of all DataKits installed in that workspace. Click on the DataKit host to connect to the DataKit remotely, and view the running status of the DataKit on the host, including version, running time, publishing data and collector running status.

View Collector Configuration¶

After connecting to the DataKit remotely, click "Collector Configuration" to view the list of collectors and Sample that have been configured (all Sample files that are currently supported by DataKit).

• Configured list: you can view all conf files under it.
• Sample list: You can view all the sample files under it.
• Help: You can view the corresponding collector help document

SNMP Profile Management¶

Open Collector Configuration → SNMP Profiles to view built-in profiles and create, import, edit, validate or delete native SNMP .yaml profiles. Changes require DCA configuration management permission. Container deployments are read only.

• Built-in files in conf.d/snmp/profiles/ are read only. Use Copy to custom to create an editable copy.
• Custom files are saved to conf.d/snmp/extra_profiles/ and take precedence over built-in files with the same name. Deleting an override restores the built-in definition after reload.
• File names must start with an ASCII letter, digit or underscore, contain only ASCII letters, digits, underscores, hyphens and dots, end in .yaml, and be no longer than 128 characters. Content is limited to 1 MiB. Prefix inheritance templates with _.
• Saving validates YAML, inheritance and metric definitions. Refresh before editing a file changed by another user. Referenced templates cannot be deleted unless a built-in replacement exists.
• Saving only writes the file; it does not apply changes automatically. After saving, select Reload DataKit to apply changes. This reloads all collectors on the host and briefly pauses collection. Check runtime status and logs to confirm SNMP collection.

To manage SNMP profiles, use DCA 0.3.0 or later and update DataKit and dk_upgrader on the managed host together. If the page reports that the current version does not support file management or reloading, update the relevant components and retry.

This feature supports native SNMP profiles; Zabbix and Prometheus profile formats are outside its scope. See SNMP for profile authoring instructions.

View Log Pipeline¶

After connecting to the DataKit remotely, click「Pipelines」to view the Pipeline file that comes with the DataKit by default. Refer to the document text data processing for Pipeline.

View the Blacklist¶

After connecting to DataKit remotely, click "Blacklist" to view the blacklist configured in the TrueWatch. As shown in the following figure, source = default and (status in [unknown]) is the configured blacklist condition.

Note: The blacklist files created through TrueWatch are stored in the path: /usr/local/datakit/data/.pull.

View DataKit log¶

After connecting to DataKit remotely, click "Log" to view the logs of DataKit and also the logs can be exported.

Select DataKit runtime logs or HTTP access logs. The initial snapshot reads the latest 1,000 lines. Load earlier logs in pages of up to 1,000 lines. Changes to the log file may require reloading; viewing historical logs requires matching DCA and DataKit updates.

Search covers loaded content only. Display and paused buffers each default to 10,000 lines, selectable as 5,000 / 10,000 / 50,000, with a separate 20 MiB UTF-8 text cap per buffer and discarded-line counts. Paging back retains earlier content and may evict newer cached rows.

Wrapping is enabled by default; turn it off to scroll horizontally through long lines. Matching entries retain their stack traces; click a line number to inspect surrounding cached lines.

Scrolling up stops following and buffers new logs. Back to latest resumes display. Pausing display keeps receiving data. Transient failures retry a bounded number of times while retaining existing content. Reconnection reads the file tail again, so duplicates or gaps may occur. Sign in again after session expiration to continue.

Controls include wrapping, font size, focus view, copying a line/context, and exporting filtered results. Management accounts can also download the log file. Clearing the display removes browser buffers only; it does not delete the host log file. File viewing is unavailable for stdout logging.

Changelog¶

0.5.0 (2026/11/05)¶

• Added OpenAPI with an instance-specific deployment credential for discovering connected workspaces and DataKits and managing collector configurations and custom SNMP profiles in batches (#3251).
• Added batch configuration in the UI with reference-host, collector and built-in template selection, per-host diff checks and removal of ineligible targets (#3252, #3253).
• Batch operations are grouped by task with progress, per-host results with loading/refresh controls, failed-target retries, pause/resume and automatic backups before updates or deletion. Operations on the same host run serially.
• Added DCA_LOGIN_URL and DCA_DOC_URL to configure browser login and documentation roots separately for private TrueWatch deployments.
• Fixed empty collector filters for older DKs, untranslated error messages and session recovery issues.
• Batch configuration requires matching DataKit and dk_upgrader updates and persistent tasks through DCA_DB_PATH. Configure OpenAPI credentials with DCA_OPENAPI_TOKEN; browser access continues to use existing SSO and management permissions.

0.3.0 (2026/10/28)¶

• Redesigned host management with collector and tag filters, global sorting, pagination, version display and bulk operations; fixed multi-value regular expression matching and invalid expression feedback.
• Single-host and bulk upgrades and restarts verify host status and the resulting version or start time after submission, distinguishing submitted, verified and timed-out unconfirmed operations.
• Added SNMP Profile management for creating, importing, editing, validating, copying and deleting custom files, with read-only built-in files, capability detection and reload guidance.
• Unified configuration, Pipeline and Profile editing with keyboard shortcuts, find and replace, sample testing and unsaved-change protection; fixed Pipeline test error messages.
• Improved log history pagination, wrapping, filtering and export, and added URL path token redaction. Fixed workspace and account refresh after session recovery and language switching for controls and relative times.

0.1.9 (2026/08/19)¶

• DataKit list now distinguishes the latest v1 and v2 versions to avoid incorrect cross-major upgrade status.

0.1.8 (2026/08/12)¶

• Improved DataKit list search debouncing to avoid duplicate queries and error notifications caused by canceled requests during rapid input.
• Improved DCA WebSocket connection and watcher lifecycle handling for better stability during connection changes and unexpected disconnections.

0.1.7 (2026/06/18)¶

• DataKit list now supports workspace search filtering, improving workspace switching in multi-workspace scenarios.
• DataKit log page now supports connection status, pause/resume, clear, search highlighting, log level filtering, auto-follow, reconnect, and log download.
• Improved the DataKit running status page to show runtime overview, basic information, enabled collectors, and collector runtime metrics.
• Improved DataKit list filtering, searching, and operation interactions for better usability in advanced filtering scenarios.
• Improved disabled action hints for reload and upgrade operations by showing the unavailable reason.
• Fixed page loading failures when some DataKit runtime information is unavailable.
• Fixed log page access failures in some error scenarios.
• Improved the stability and security of collector configuration, Pipeline, and upgrade operations.

0.1.6 (2026/01/14)¶

• Add support for reporting DataKit availability metric dk_host_available

0.1.5 (2025/11/06)¶

• Add DCA service Prometheus metrics, including DataKit count and network request metrics.

0.1.4 (2025/10/14)¶

• Support creating DataKit collector configuration file.

0.1.3 (2025/08/13)¶

• Batch operations now support selecting all DataKits for batch processing.
• When filtering the DataKit list, filtering is supported based on fields such as version, operating system, and user-configured global tags.
• A new column display feature is added to the DataKit list, allowing users to customize the displayed columns.

0.1.2(2025/07/09)¶

• Add support for English version

0.1.1(2025/05/15)¶

• Add container ENV for DCA backend Prometheus exporter URL (DCA_PROM_LISTEN)
• Refactor DCA build

0.1.0(2024/11/27)¶

• Refactored the DCA underlying framework to use WebSocket protocol for communication, making it easier to manage DataKit in different network environments.
• Added the functionality to manage the main configuration of DataKit.
• Added support for TLS configuration.
• Changed the "Reload" feature of DataKit to "Restart".