Logthread Agent

One agent for logs and metrics from any machine: Windows Server (Event Log, performance counters), IIS, SQL Server (metrics, slowest statements, ERRORLOG), Linux hosts (host metrics, journal, auth log), Docker and Podman, NGINX, Apache, PostgreSQL, MySQL, Redis, MongoDB, Kafka, RabbitMQ and Elasticsearch, a local OTLP receiver for your applications, and zero-code autotrace (beta). Fleet mode manages it from the app. It is an OpenTelemetry Collector distribution (Apache-2.0) built with the OpenTelemetry Collector Builder, plus Logthread profiles, so it sends standard OTLP to your Logthread ingest endpoint with your ingest key and nothing else.

• Binary: logthread-agent (one file per OS; logthread-agent --version).
• Built from OpenTelemetry Collector and Collector Contrib v0.163.0.
• Everything is Apache-2.0, MIT or BSD. A CycloneDX SBOM is published next to each download.
• Downloads, checksums and SBOMs are at https://downloads.logthread.com/agent/ (the Developers page lists every file).

Status. The Linux and Fleet paths are verified. The Windows, IIS and SQL Server parts and the macOS build are beta: they work as described here but have had less real-world use, and the Windows zip is unsigned (checksums only). Tell us what you see on your machines.

Install#

You need a Logthread ingest key (Ingest keys in the app; it is shown once). It is never written into a config file. In the commands below, replace YOUR_INGEST_KEY with it.

Linux#

Debian, Ubuntu, RHEL, Rocky, Alma, Amazon Linux, Fedora, SUSE and others, on x64 or arm64.

curl -sSL https://downloads.logthread.com/agent/install.sh | sudo sh -s -- \
  --key YOUR_INGEST_KEY --profiles linux-host

The installer detects the CPU (amd64 or arm64) and the package manager, downloads the .deb, .rpm or tarball from https://downloads.logthread.com/agent/<version>/, verifies its SHA-256 against SHA256SUMS.txt, installs it, writes /etc/logthread-agent/agent.env (mode 0600, holds the key), enables the profiles and starts the logthread-agent systemd service. Running it again with other options reconfigures the install.

Manual install: sudo dpkg -i logthread-agent_<v>_linux_<arch>.deb or sudo rpm -U logthread-agent_<v>_linux_<arch>.rpm, then sudo editor /etc/logthread-agent/agent.env (set LOGTHREAD_INGEST_KEY), sudo logthread-agent-profile enable linux-host and sudo systemctl enable --now logthread-agent.

Layout:

Manage profiles with logthread-agent-profile list | enable <p> | disable <p> | set <p>.... It validates the resulting configuration first and restarts the service. The service runs as the unprivileged user logthread-agent (member of adm and systemd-journal). Enabling the docker profile adds a systemd drop-in that runs the service as root, because /var/lib/docker/containers is root-only.

Windows#

Windows Server 2016 and later, and Windows 10 and 11, x64 (beta). From an elevated PowerShell:

Invoke-WebRequest https://downloads.logthread.com/agent/install.ps1 -OutFile install.ps1
.\install.ps1 -Key YOUR_INGEST_KEY -Profiles windows-server,iis
# SQL Server with top queries (a DSN is required, see the sqlserver profile below):
.\install.ps1 -Key YOUR_INGEST_KEY -Profiles windows-server,iis,sqlserver `
  -SqlServerDsn 'server=.;port=1433;Integrated Security=SSPI;encrypt=true;TrustServerCertificate=true'

The script downloads logthread-agent_<v>_windows_amd64.zip, verifies its SHA-256, installs to C:\Program Files\Logthread\Agent, writes the profiles to C:\ProgramData\Logthread\Agent\conf.d, registers the Windows service LogthreadAgent (LocalSystem, automatic start, restart on failure) and starts it. The key lives only in the service's own environment (HKLM\SYSTEM\CurrentControlSet\Services\LogthreadAgent, value Environment); that registry key and C:\ProgramData\Logthread\Agent are locked to SYSTEM and Administrators. Offline: .\install.ps1 -Key YOUR_INGEST_KEY -LocalZip .\logthread-agent_0.2.5_windows_amd64.zip (keep SHA256SUMS.txt next to the zip to have it verified).

Options: -Profiles, -Endpoint, -Fleet, -Labels, -SqlServerDsn, -IisLogDir (a non-default IIS log folder), -Version, -NoStart, -Uninstall, -Purge. Re-run it to change profiles. The agent's own log is C:\ProgramData\Logthread\Agent\logs\agent.log (not rotated; it only contains start-up and error lines). The zip is unsigned in this release (checksums only); a signed MSI follows once a code-signing certificate exists.

Docker#

There is no hosted Logthread Agent container image yet. To collect Docker logs and per-container metrics, install the agent on the Docker host with the Linux package and enable the docker profile (it runs the service as root so it can read /var/lib/docker/containers):

curl -sSL https://downloads.logthread.com/agent/install.sh | sudo sh -s -- \
  --key YOUR_INGEST_KEY --profiles linux-host,docker

Applications in containers can send traces, metrics and logs to the otlp profile of an agent running on the host (127.0.0.1:4318), or straight to Logthread with OpenTelemetry.

macOS#

macOS (beta) is a tarball only. Download logthread-agent_<v>_darwin_<arch>.tar.gz from https://downloads.logthread.com/agent/<v>/ (arm64 for Apple silicon, amd64 for Intel), verify it against SHA256SUMS.txt in the same folder, copy the binaries to /usr/local/lib/logthread-agent/, the profiles to /usr/local/etc/logthread-agent/conf.d/, and load com.logthread.agent.plist from /Library/LaunchDaemons (add LOGTHREAD_INGEST_KEY to its EnvironmentVariables). Only the otlp profile is meant for macOS in this release; add your own fragment for anything else.

Profiles#

The easiest way to choose profiles is Integrations in the app: pick the software, answer a few questions and run the command it gives you. The Integrations guide lists every integration with its setup.

A profile is a YAML fragment. The agent always loads base.yaml (the Logthread exporter, queue, memory limiter, health check) and then the enabled profiles.

Windows profiles load only on Windows (the receivers are Windows-only). Everything else runs anywhere the agent runs. Settings that depend on the host are environment variables, listed at the top of each profile.

autotrace (beta)#

Traces from services you cannot change, on Linux. install.sh --profiles linux-host,autotrace downloads the add-on logthread-agent-autotrace_<v>_linux_<arch>.tar.gz (the upstream OpenTelemetry eBPF Instrumentation v0.15.2 binary with its LICENSE and NOTICE, Apache-2.0), verifies its SHA-256 and installs it in /usr/lib/logthread-agent/autotrace/. It refuses on kernels without BTF (/sys/kernel/btf/vmlinux).

• OBI runs as its own service, logthread-agent-autotrace, as root with a fixed capability set (BPF, PERFMON, SYS_PTRACE, NET_RAW, NET_ADMIN, DAC_READ_SEARCH, CHECKPOINT_RESTORE, SYS_RESOURCE, SYS_ADMIN), because eBPF needs them and the agent does not run as root. It sends OTLP to the agent on 127.0.0.1:4319, and the agent forwards with its queue and your key: OBI never reads agent.env or the key.
• Settings: /etc/logthread-agent/autotrace.env. LOGTHREAD_AUTOTRACE_PORTS (default 80,443,3000,5000,8000-8999) picks the processes by listening port; keep database ports out. OBI's own settings are /usr/share/logthread-agent/autotrace/obi.yaml; to change them, copy it to /etc/logthread-agent/autotrace.yaml and set OTEL_EBPF_CONFIG_PATH to it. After a change: sudo systemctl restart logthread-agent-autotrace.
• Name each service with OTEL_SERVICE_NAME in its own environment; otherwise it is named after its executable (node, python3.13).
• logthread-agent-profile enable autotrace starts the service and disable autotrace stops it. Logs: journalctl -u logthread-agent-autotrace.
• Requirements, what it captures, how to check it works, troubleshooting and the limits (Linux only, single-span traces for some languages, statement text) are in the zero-code tracing guide. In containers and Kubernetes, run OBI's own image instead (Docker, Compose and DaemonSet setups in the same guide).

IIS#

Logs are read from %SystemDrive%\inetpub\logs\LogFiles\W3SVC*\*.log (-IisLogDir or LOGTHREAD_IIS_LOG_DIR for another folder, with forward slashes). The #Fields: header of each file names the columns, so custom field selections work. The IIS names become the preset's names (cs-method is method, sc-status is status as an integer, time-taken is time_taken_ms, ...); unknown fields keep their W3C name. Date and time become the event time (UTC), the severity follows the status (5xx ERROR, 4xx WARN), and the body is GET /path 200 125ms. On first start the agent reads files modified in the last 48 hours from the beginning (so the header is known) and then follows them. Do not also attach the iis-w3c preset to this source: the fields are already extracted. The cs(Cookie) field is always dropped; set LOGTHREAD_IIS_DROP_QUERY=true to also drop the URI query string.

SQL Server#

Give the agent a login that can read server state and nothing else:

CREATE LOGIN logthread_agent WITH PASSWORD = '...';
GRANT VIEW SERVER STATE TO logthread_agent;        -- SQL Server 2022+: VIEW SERVER PERFORMANCE STATE
GRANT VIEW ANY DEFINITION TO logthread_agent;
GRANT VIEW ANY DATABASE TO logthread_agent;

Set LOGTHREAD_SQLSERVER_DSN, a go-mssqldb connection string, for example server=db01;port=1433;user id=logthread_agent;password=...;encrypt=true;TrustServerCertificate=true (Windows: server=.;port=1433;Integrated Security=SSPI;... under LocalSystem, if that login has the grants). Without a DSN only the Windows performance counters are collected and there are no top queries. The ERRORLOG is read from C:\Program Files\Microsoft SQL Server\MSSQL*\MSSQL\Log\ERRORLOG (LOGTHREAD_SQLSERVER_ERRORLOG_DIR to move it) and /var/opt/mssql/log/errorlog. Statement text is obfuscated by the receiver (literals and parameter values become ?) and the execution plan is removed on the host before sending, because plans can embed compiled parameter values.

Configuration#

• Environment (agent.env, or the Windows service environment): LOGTHREAD_INGEST_KEY, LOGTHREAD_ENDPOINT (default https://ingest.logthread.com), LOGTHREAD_LOG_LEVEL, LOGTHREAD_LOG_FILE (the agent's own log; default stderr), LOGTHREAD_HEALTH_ENDPOINT (default 127.0.0.1:13133), LOGTHREAD_MEMORY_LIMIT_MIB (512), LOGTHREAD_QUEUE_BYTES (512 MiB on disk), LOGTHREAD_RESOURCE_DETECTORS (default [env, system]; "[env, system, ec2]" on AWS, azure, gcp, docker also available), plus the profile settings.
• Delivery tuning (all optional, in the same place):

• Proxy and TLS: the agent uses HTTPS_PROXY, HTTP_PROXY and NO_PROXY from its environment (agent.env, the Windows service environment, or -e on docker run). LOGTHREAD_PROXY_URL (for example http://user:pass@proxy:3128) names a proxy for Logthread delivery only. LOGTHREAD_CA_FILE is a PEM file of extra certificate authorities to trust, for a private CA or a TLS-inspecting proxy (tls.ca_file on the exporter); the system roots stay trusted. agent/test/verify-batching.py runs the real binary against a local sink and checks the size caps, the proxy and the CA file.
• Your own configuration: add a fragment such as /etc/logthread-agent/conf.d/90-local.yaml (C:\ProgramData\Logthread\Agent\conf.d\90-local.yaml). On Windows re-run install.ps1 after adding a file (the service command line lists the files).
• Merging: the collector merges several config files key by key. Maps are merged, lists are replaced. Profiles therefore only add map entries (receivers, processors, and *named* pipelines such as logs/iis). To extend one of them, use the same pipeline name; do not set service.extensions (only base.yaml does). Add a new pipeline of your own with a new name and the exporter otlp_http/logthread.
• Validate: logthread-agent validate --config=file:base.yaml --config=file:iis.yaml ... (with LOGTHREAD_INGEST_KEY set to any value).
• Delivery: OTLP/HTTP, gzip, retries with backoff, and a persistent sending queue on disk (LOGTHREAD_DATA_DIR), so a restart or an outage does not lose data (up to LOGTHREAD_QUEUE_BYTES). The agent reports its own counters on 127.0.0.1:8888/metrics (otelcol_exporter_sent_log_records, otelcol_exporter_send_failed_*).

Fleet mode#

With --fleet (-Fleet on Windows, LOGTHREAD_FLEET=true in the environment or the container), the agent starts under the OpenTelemetry OpAMP Supervisor (bundled as logthread-agent-supervisor), connects to wss://<endpoint>/v1/opamp with Authorization: Bearer <ingest key>, and appears in Fleet. It reports health and its effective configuration; configurations pushed from Logthread (with their selector on labels such as env and role, set by --labels env=prod,role=web) are merged on top of your local profiles by the supervisor, with rollout and rollback from the app. The supervisor config is generated (/var/lib/logthread-agent/supervisor/supervisor.yaml, ...\data\supervisor\supervisor.yaml on Windows) and never contains the key.

This matches what Fleet supports today: the Supervisor, not the collector's opamp extension alone, because only the Supervisor can apply a pushed configuration. The agent also contains the opamp extension for the read-only alternative (status and effective config only, no remote config): enable the fleet-readonly profile, which sets LOGTHREAD_OPAMP_ENDPOINT (default wss://ingest.logthread.com/v1/opamp). Because maps merge and lists are replaced, a pushed config that defines the same pipeline names as a profile replaces that pipeline's component lists. Pushed configs should use the snake_case component names of this release (otlp_http/logthread, file_log, host_metrics); the old names (otlphttp, filelog, hostmetrics) still load but define a separate component.

Uninstall#

• Linux: curl -sSL https://downloads.logthread.com/agent/install.sh | sudo sh -s -- --uninstall (add --purge to delete /etc/logthread-agent, which holds the key, and the state), or apt remove logthread-agent / dnf remove logthread-agent.
• Windows: .\install.ps1 -Uninstall (add -Purge to delete C:\ProgramData\Logthread\Agent).
• Docker: docker rm -f logthread-agent (and docker volume rm logthread-agent-state).

Troubleshooting#

What is collected, and privacy#

• Metrics: system and per-profile metrics listed above; resource attributes host.name, host.ip, os.type and the profile's service.name (for example windows-server, iis, sqlserver, linux-host, docker).
• Which machine sent it: every record (logs, metrics and traces) carries host.name and host.ip, the machine's main address: the first that is not loopback or link-local. Behind NAT or a load balancer this still names the server itself. Search it with res.host.ip:10.0.0.4. To leave it out, drop host.ip with a pipeline.
• Logs: the sources of the enabled profiles only. Nothing else on the machine is read. Files are read from where they are; the agent never writes to them.
• Windows Event Log: channel, provider, event id, level, task, record id and message text. The structured event data is not sent. Message texts can contain names; use the Security profile and Event Log sources deliberately.
• IIS: client IP, user name (if any), method, URI stem and (optionally) query, user agent, status and timings. Cookies are never sent.
• SQL Server: normalised statement text with literals and parameter values replaced by ?, timings, counts, wait types, database and login names; no execution plans, no data.
• Docker: container log lines and metrics, as written by the containers.
• Transport: OTLP/HTTP over TLS to your Logthread ingest endpoint with your ingest key. The key is held in the service environment (Windows), the 0600 agent.env (Linux) or your orchestrator's secret store. The agent opens no inbound port except the optional local OTLP receiver (loopback by default) and the loopback health and metrics endpoints.

Verify a Windows install#

After installing on Windows (beta), check, in an elevated PowerShell:

Get-Service LogthreadAgent                                  # Status: Running
Invoke-RestMethod http://127.0.0.1:13133/                  # the agent's health endpoint
Get-Content "C:\ProgramData\Logthread\Agent\logs\agent.log" -Tail 50   # start-up and error lines

Then open Sources in the app: the host appears with its windows-server, iis or sqlserver service within a minute or two. If it does not, see Troubleshooting.

Next: manage many agents from the app with Fleet.