LOG SOURCE WATCH · DOCUMENTATION

Product documentation

Installation, architecture, operations and licensing reference for Log Source Watch 4.9.3.

Overview

Log Source Watch monitors expected log continuity in Splunk Enterprise. The application identifies a source as a unique index + host pair, records the latest observed event timestamp, applies a per-source silence threshold and exposes the resulting operational state.

What LSW is designed to answer: “Are the log sources we expect still producing telemetry within their own reporting policy?” It is not a host-uptime monitor.

Requirements

Splunk Enterprise with KV Store available.
admin or sc_admin access for Initial Setup and management workflows.
No third-party Python packages or external SaaS dependency are required by the Splunk app.
The app packages custom search commands. Restart Splunk after installation or an upgrade that changes commands.conf before relying on the license commands.

Compatibility: publish only Splunk versions that you have actually runtime-tested. Static validation alone does not replace a clean-install, upgrade and AppInspect acceptance test on the target version.

Installation

Splunk Web

Open Apps → Manage Apps.
Select Install app from file.
Upload the Log Source Watch .tgz package.
Restart Splunk if requested. Because LSW includes custom search commands, one restart is recommended before Initial Setup.
Open Log Source Watch → Initial Setup.

Command line

$SPLUNK_HOME/bin/splunk install app logsource_watch-4.9.3.tgz -auth admin:******** $SPLUNK_HOME/bin/splunk restart

Environment-specific configuration and a paid license file belong under $SPLUNK_HOME/etc/apps/logsource_watch/local/. Do not modify packaged files under default/.

Initial Setup

Initial Setup verifies the packaged KV Store schema, discovers the first source scope, enrolls the selected index + host pairs, seeds latest observations and builds canonical state.

Select an index.
Select a baseline lookback window.
Select the default silence threshold.
Review the source preview.
Run Initialize Log Source Watch.

The status banner has three outcomes:

Status	Meaning
Initial Setup Required	No inventory is registered yet.
Log Source Watch Successfully Initialized	Inventory exists and canonical state contains one row per registered source. Some rows may legitimately be NO LOG OBSERVATION.
Initial Setup Needs Attention	Inventory and canonical state counts do not match and state should be rebuilt before relying on monitoring results.

Core concepts

Monitored Source

One source is one unique index + host pair. The same host in two indexes is two independent sources. Internally, the stable key is:

_key = sha256(index . "|" . host)

Policy vs. operational state

status is configured policy: active, maintenance or retired. effective_state is the derived operational result shown to operators.

State model

RETIREDLifecycle has explicitly removed the source from active monitoring capacity.

MAINTENANCEMaintenance is active until a future epoch or until manually cleared.

NO LOG OBSERVATIONNo last_seen value exists for the registered source.

SILENTnow() - last_seen is greater than threshold_seconds.

OKThe source is reporting inside its allowed silence window.

RETIRED → MAINTENANCE → NO LOG OBSERVATION → SILENT → OK

This precedence is implemented by the lsw_calculate_state macro and is also used by the interactive UI for immediate consistency.

Management

The Management workspace reads app-owned KV Store data and supports immediate policy changes without a full-page reload.

Action	Behavior
Threshold	Whole-minute value from 1 to 10,080 minutes. Stored as integer seconds.
Activate	Sets lifecycle to `active` and clears maintenance.
Retire	Sets lifecycle to `retired`. The source remains in history but no longer consumes licensed monitored-source capacity.
Maintenance	Timed maintenance or maintenance until manually cleared.
Bulk Actions	Applies policy to a reviewed filtered scope. A hard 10,000-source safety limit is enforced.

Discovery

Discovery is operator-driven. The page does not launch a broad indexed search merely by opening it. After an index and lookback are selected, LSW uses tstats to find observed index + host pairs and compares them with inventory.

Enrollment writes, in order, to lsw_inventory, lsw_lastseen, lsw_state and lsw_audit. Discovery enrollment is capped at 10,000 sources per operation.

Maintenance

A source in maintenance can use either a future maintenance_until epoch or 0 for “until cleared”. Timed maintenance is automatically returned to ACTIVE by LSW_Expire_Maintenance. Automatic expiry is written to the Audit Trail with scheduler origin.

Reports

Report	Purpose
Silent Sources	Read-only report of sources whose silence threshold has been exceeded.
Application Health	Scheduler freshness, KV Store readiness and source-state statistics.
Audit Trail	Enrollment, threshold, maintenance and lifecycle changes, including automatic timed-maintenance expiry.

Machine-readable exports are maintained as lsw_silent_hosts.csv and lsw_health.csv under the app lookups directory.

Scheduled jobs

Search	Cadence	Role
LSW_Update_LastSeen	Every 5 minutes	Updates latest observations for active or maintenance sources.
LSW_Expire_Maintenance	Minute +1 of the 5-minute cycle	Ends timed maintenance windows and writes an audit event.
LSW_Build_State	Minute +2	Reconciles canonical state into `lsw_state`.
LSW_Export_SilentHost_File	Minute +3	Refreshes the silent-source CSV export.
LSW_Export_Health_File	Minute +4	Refreshes the health CSV export.

The staggered schedule avoids dispatching all internal jobs at the same instant.

KV Store data model

Collection	Purpose	Key fields
lsw_inventory	Authoritative source identity and policy	`index, host, status, threshold_seconds, maintenance_until, change_ref`
lsw_lastseen	Latest event observation	`index, host, last_seen, updated_at`
lsw_state	Materialized canonical state	`effective_state, age_seconds, threshold_seconds, alarm`
lsw_audit	Administrative and automatic policy-change history	`actor, scope, operation, old_, new_, details`
lsw_health	Reserved/persisted health integration state	`component, last_run, scheduler_status`

Licensing

Edition	Standard capacity	Standard deployment model
Community	Up to 100	Single standalone environment; no paid file required.
Professional	101–1,000	One production environment.
Enterprise	1,001–5,000	SHC and multiple production environment rights can be included.
Enterprise Plus	Above 5,000 / custom / unlimited	Custom capacity and topology.
Service Provider	Custom	MSP/MSSP/hosted-service use when explicitly granted.

A paid license is a signed JSON entitlement placed at:

$SPLUNK_HOME/etc/apps/logsource_watch/local/lsw_license.json

Check status with:

| lswlicense

Capacity behavior: reaching the limit does not switch off existing monitoring. Operations that would add monitored capacity are blocked until capacity is reduced or a suitable license is installed.

Redistribution, OEM, bundling and resale are separate rights unless explicitly granted.

Upgrade

Back up the existing app and KV Store according to your normal Splunk change process.
Install the new package over the existing app.
Preserve environment-specific files under local/, including lsw_license.json.
Restart Splunk when the release changes custom search commands or when Splunk requests it.
Open Application Health and confirm internal schedulers advance normally.
Smoke-test Overview, Management, Bulk Actions, Discover, Reports and license status.

Troubleshooting

Unknown search command 'lswlicense'

The custom-command configuration has not been loaded by the current Splunk process. Restart Splunk once, then verify:

| lswlicense

With no paid license file installed, the expected result is Community Edition with a 100-source capacity.

Initial Setup Needs Attention

Compare lsw_inventory and lsw_state. A successful initialized state has one canonical-state row per inventory row. lsw_lastseen may legitimately contain fewer rows because sources without observations are represented as NO LOG OBSERVATION.

A source is SILENT

Check last_seen, source threshold and source lifecycle. SILENT means the latest observed event is older than the configured threshold; it does not by itself identify whether the problem is the source, transport, parsing, indexing or permissions.

Security and operational boundaries

Management views are restricted to admin / sc_admin by packaged metadata.
The app stores configuration and operational state in app-owned KV Store collections.
The packaged Python runtime uses only the Python standard library plus Splunk-provided modules.
No private license-signing key is included in the Splunk app. Only the public verification key is packaged.
Discovery event searches are explicitly operator-driven and bounded by selected index/lookback.
Before public release, run current Splunk AppInspect against the exact release TGZ and complete clean-install, upgrade, load and topology tests.

Commercial deployment: the bundled license terms should be reviewed by qualified legal counsel before monetization. Security and performance must also be validated in the customer’s actual Splunk topology.

Need a license?

Community is free up to 100 sources.

Commercial tiers and invoice / PO options are available on the product page.

View pricing