# win_eventlog – Manage Windows event logs

New in version 2.4.

- Synopsis

- Parameters

- See Also

- Examples

- Return Values

- Status

## Synopsis

- Allows the addition, clearing and removal of local Windows event logs, and the creation and removal of sources from a given event log. Also allows the specification of settings per log and source.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
category_file path |  | For one or more sources specified, the path to a custom category resource file.
maximum_size string |  | The maximum size of the event log. Value must be between 64KB and 4GB, and divisible by 64KB. Size can be specified in KB, MB or GB (e.g. 128KB, 16MB, 2.5GB).
message_file path |  | For one or more sources specified, the path to a custom event message resource file.
name string / required |  | Name of the event log to manage.

overflow_action
string

Choices:
- DoNotOverwrite
- OverwriteAsNeeded
- OverwriteOlder

The action for the log to take once it reaches its maximum size.
For `DoNotOverwrite`, all existing entries are kept and new entries are not retained.
For `OverwriteAsNeeded`, each new entry overwrites the oldest entry.
For `OverwriteOlder`, new log entries overwrite those older than the `retention_days` value.

parameter_file path |  | For one or more sources specified, the path to a custom parameter resource file.
retention_days integer |  | The minimum number of days event entries must remain in the log. This option is only used when `overflow_action` is `OverwriteOlder`.
sources list |  | A list of one or more sources to ensure are present/absent in the log. When `category_file`, `message_file` and/or `parameter_file` are specified, these values are applied across all sources.

state
string

Choices:
- absent
- clear
- present ←

Desired state of the log and/or sources.
When `sources` is populated, state is checked for sources.
When `sources` is not populated, state is checked for the specified log itself.
If `state` is `clear`, event log entries are cleared for the target log.

## See Also

See also

win_eventlog_entry – Write entries to Windows event logs

  The official documentation on the win_eventlog_entry module.

## Examples

    - name: Add a new event log with two custom sources
      win_eventlog:
        name: MyNewLog
        sources:
          - NewLogSource1
          - NewLogSource2
        state: present

    - name: Change the category and message resource files used for NewLogSource1
      win_eventlog:
        name: MyNewLog
        sources:
          - NewLogSource1
        category_file: C:\NewApp\CustomCategories.dll
        message_file: C:\NewApp\CustomMessages.dll
        state: present

    - name: Change the maximum size and overflow action for MyNewLog
      win_eventlog:
        name: MyNewLog
        maximum_size: 16MB
        overflow_action: DoNotOverwrite
        state: present

    - name: Clear event entries for MyNewLog
      win_eventlog:
        name: MyNewLog
        state: clear

    - name: Remove NewLogSource2 from MyNewLog
      win_eventlog:
        name: MyNewLog
        sources:
          - NewLogSource2
        state: absent

    - name: Remove MyNewLog and all remaining sources
      win_eventlog:
        name: MyNewLog
        state: absent

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
entries integer | success | The count of entries present in the event log. Sample: 50
exists boolean | success | Whether the event log exists or not. Sample: True
maximum_size_kb integer | success | Maximum size of the log in KB. Sample: 512
name string | always | The name of the event log. Sample: MyNewLog
overflow_action string | success | The action the log takes once it reaches its maximum size. Sample: OverwriteOlder
retention_days integer | success | The minimum number of days entries are retained in the log. Sample: 7
sources list | success | A list of the current sources for the log. Sample: ['MyNewLog', 'NewLogSource1', 'NewLogSource2']
sources_changed list | always | A list of sources changed (e.g. re/created, removed) for the log; this is empty if no sources are changed. Sample: ['NewLogSource2']

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Andrew Saraceni (@andrewsaraceni)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.