Component logs¶
AppControl can retrieve logs from the agent assigned to a component. Open an application map, select a component, then open Logs.
Choose the right source¶
| Source | Configuration | Persistence | Best use |
|---|---|---|---|
| Command output | None | Stored by AppControl | Inspect stdout/stderr and status returned by start, stop and custom commands |
| Live process output | None | In-memory agent buffer | Inspect recent stdout/stderr emitted while the agent is connected |
| Log file | Absolute path on the agent machine | Stored by the application | Tail Linux or Windows application logs |
| Windows Event Log | Log name, with optional source and level | Stored by Windows | Inspect Application, System or Security events |
| Diagnostic command | A read-only command | Result shown on demand | Query application or operating-system status through the agent |
Command output and live process output are different. Command output is the audited history of commands executed by AppControl. The live process source is the agent's bounded, in-memory buffer and is cleared when the agent restarts.
Add a source in the UI¶
- Assign an enrolled agent to the component.
- Open the component's Logs tab.
- Select +.
- Choose Log File, Windows Event Log or Diagnostic Command.
- Enter a display name and the source-specific values.
For a file source, use an absolute path that exists on the agent machine, such
as /var/log/my-application/application.log or
C:\ProgramData\MyApplication\logs\application.log.
For a Windows event source:
- Event Log Name is normally
Application,SystemorSecurity. - Event Source is optional and restricts results to one Windows provider.
- The agent service account must have permission to read the selected log.
The Logs tab supports a line limit, a time range and a text filter. Requests are limited to 1,000 lines to protect the agent and backend.
Diagnostic commands run synchronously through the assigned agent and display their exit code, duration, stdout and stderr in the same tab. Start and stop commands use detached execution; their persisted return confirms whether the process was launched, while subsequent application output must be read from the application's file, Windows Event Log, or another configured source.
Add a source with the API¶
Set the connection values once:
export APPCONTROL_URL="https://appcontrol.example.com"
export APPCONTROL_TOKEN="<access-token>"
export COMPONENT_ID="<component-uuid>"
Create a Linux file source from the supplied example:
curl --fail-with-body \
-X POST "$APPCONTROL_URL/api/v1/components/$COMPONENT_ID/log-sources" \
-H "Authorization: Bearer $APPCONTROL_TOKEN" \
-H "Content-Type: application/json" \
--data @examples/log-source-file.json
For Windows Event Log, adapt
examples/log-source-windows-event.json, especially
event_log_source, then send it to the same endpoint.
Retrieve live process output:
curl --fail-with-body \
-H "Authorization: Bearer $APPCONTROL_TOKEN" \
"$APPCONTROL_URL/api/v1/components/$COMPONENT_ID/logs?source=process&lines=100&since=1h"
Retrieve a configured file or event source by using the source UUID returned when it was created:
SOURCE_ID="<log-source-uuid>"
curl --fail-with-body \
-H "Authorization: Bearer $APPCONTROL_TOKEN" \
"$APPCONTROL_URL/api/v1/components/$COMPONENT_ID/logs?source=$SOURCE_ID&lines=200&filter=ERROR&since=24h"
Permissions and sensitive logs¶
- Viewing logs requires Operate permission on the component.
- Creating, changing or deleting a source requires Edit permission.
- Mark a source as sensitive when it can expose credentials, personal data or business data. Sensitive sources require Edit permission even for reads.
- Every log access is written to the AppControl audit trail.
Troubleshooting¶
| Symptom | Check |
|---|---|
No agent is assigned |
Assign an enrolled agent to the component |
| HTTP 503 | Confirm that the agent and its gateway are connected |
| File cannot be read | Verify the absolute path and agent service-account permissions |
| Windows Event Log is empty | Verify the log name, provider filter, level and service-account permissions |
| Live process output is empty | Run a component command and confirm the agent has not restarted |
Log retrieval times out after 30 seconds. File and event-log errors returned by the agent are surfaced by the API rather than replaced with empty results.