README.md

Windows Event Log Receiver

Status
Stability	alpha: logs
Unsupported Platforms	darwin, linux
Distributions	contrib
Issues
Code Owners	@armstrmi, @pjanotti

Tails and parses logs from windows event log API using the opentelemetry-log-collection library.

Configuration Fields

Field	Default	Description
channel	required	The windows event log channel to monitor
max_reads	100	The maximum number of records read into memory, before beginning a new batch
start_at	end	On first startup, where to start reading logs from the API. Options are beginning or end
poll_interval	1s	The interval at which the channel is checked for new log entries. This check begins again after all new bodies have been read.
attributes	{}	A map of key: value pairs to add to the entry's attributes.
resource	{}	A map of key: value pairs to add to the entry's resource.
operators	[]	An array of operators. See below for more details
raw	false	If true, the windows events are not processed and sent as XML. If used in combination with exclude_providers, each event will be processed in order to determine its provider name.
exclude_providers	[]	One or more event log providers to exclude from processing.
storage	none	The ID of a storage extension to be used to store bookmarks. Bookmarks allow the receiver to pick up where it left off in the case of a collector restart. If no storage extension is used, the receiver will manage bookmarks in memory only.
retry_on_failure.enabled	false	If true, the receiver will pause reading a file and attempt to resend the current batch of logs if it encounters an error from downstream components.
retry_on_failure.initial_interval	1 second	Time to wait after the first failure before retrying.
retry_on_failure.max_interval	30 seconds	Upper bound on retry backoff interval. Once this value is reached the delay between consecutive retries will remain constant at the specified value.
retry_on_failure.max_elapsed_time	5 minutes	Maximum amount of time (including retries) spent trying to send a logs batch to a downstream consumer. Once this value is reached, the data is discarded. Retrying never stops if set to 0.
remote	object	Remote configuration for connecting to a remote machine to collect logs. Includes server (the address of the remote server), with username, password, and optional domain.

Operators

Each operator performs a simple responsibility, such as parsing a timestamp or JSON. Chain together operators to process logs into a desired format.

• Every operator has a type.
• Every operator can be given a unique id. If you use the same type of operator more than once in a pipeline, you must specify an id. Otherwise, the id defaults to the value of type.
• Operators will output to the next operator in the pipeline. The last operator in the pipeline will emit from the receiver. Optionally, the output parameter can be used to specify the id of another operator to which logs will be passed directly.
• Only parsers and general purpose operators should be used.

Additional Terminology and Features

• An entry is the base representation of log data as it moves through a pipeline. All operators either create, modify, or consume entries.
• A field is used to reference values in an entry.
• A common expression syntax is used in several operators. For example, expressions can be used to filter or route entries.
• timestamp parsing is available as a block within all parser operators, and also as a standalone operator. Many common timestamp layouts are supported.
• severity parsing is available as a block within all parser operators, and also as a standalone operator. Stanza uses a flexible severity representation which is automatically interpreted by the stanza receiver.

Example Configurations

Simple

Configuration:

receivers:
    windowseventlog:
        channel: application

Output entry sample:

{
    "channel": "Application",
    "computer": "computer name",
    "event_id":
    {
        "id": 10,
        "qualifiers": 0
    },
    "keywords": "[Classic]",
    "level": "Information",
    "message": "Test log",
    "opcode": "Info",
    "provider":
    {
        "event_source": "",
        "guid": "",
        "name": "otel"
    },
    "record_id": 12345,
    "system_time": "2022-04-15T15:28:08.898974100Z",
    "task": ""
}

Remote Configuration

If collection of the local event log is desired, a separate receiver needs to be created.

Requirements for Remote Configuration:

• The remote computer must enable the "Remote Event Log Management" Windows Firewall exception. Otherwise, when you try to use the session handle, the call will error with RPC_S_SERVER_UNAVAILABLE.
• The computer to which you are connecting must be running Windows Vista or later.

Single server configuration:

receivers:
    windowseventlog:
        channel: application
        remote:
            server:   "remote-server"
            username: "user"
            password: "password"
            domain:   "domain"