Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 24 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,34 +6,38 @@ A java library for parsing valid Syslog [IETF RFC 5424](https://tools.ietf.org/h
The library provides it's own parser implementations, but also exposes the Antlr generated base classes
and interfaces should you want your own implementations.


## Simple Usage

Simple Syslog provids a `Simple` class with methods for parsing syslog with the default options and as
little configuration as possible.

```java
Map<String, Object> = Simple.simpleNested5424(syslogLine);
Map<String, String> = Simple.simpleFlat5424(syslogLine);
```

Calls exist for using Readers and Consumers with the default options

The default options for RFC 5424:

- No Deviations
- OMIT policy for Nils
- Default KeyProvider

The default options for RFC 3164:

- No Deviations
- Default KeyProvider

In general, there are Simple calls for almost all the SyslogParser interface calls described below.

## Slightly less simple usage

Simple Syslog aims to provide syslog parsing that allows callers to handle syslog in the least restrictive
way.
way.

The syslog parsers do not build objects from syslog string, they call the provided syslog builder with the message
parts. This allows for custom object building.
parts. This allows for custom object building.

The default syslog builders provided allow specialization of Allowed Deviation, how to produce names for message parts,
and how to handle Nils in RFC 5424 messages.
Expand Down Expand Up @@ -82,7 +86,6 @@ Just pass a `Consumer` to the function.

```


```java
SyslogParser<Map<String, Object>> parser = new SyslogParserBuilder<Map<String, Object>>().withSyslogBuilder(new MapOfMaps5424MessageHandler()).build();
try (Reader reader = new BufferedReader(new FileReader(new File(fileName)))) {
Expand All @@ -103,7 +106,9 @@ Just pass a `Consumer` to the function.
});
}
```

#### Syslog RFC 3164

A simple, default usage to parser a Syslog RFC 3164 log line is to build a SyslogParser
with at least `SyslogSpecification` and `SyslogBuilder`.

Expand Down Expand Up @@ -136,7 +141,6 @@ Just pass a `Consumer` to the function.

```


```java
SyslogParser<Map<String, String>> parser = new SyslogParserBuilder<Map<String,String>>().forSpecification(SyslogSpecification.RFC_3164).withSyslogBuilder(new Default3164MessageHandler()).build();
try (Reader reader = new BufferedReader(new FileReader(new File(fileName)))) {
Expand Down Expand Up @@ -175,19 +179,19 @@ SyslogParser parser = new SyslogParserBuilder().forSpecification(SyslogSpecifica

### Options

While the `SyslogParserBuilder` supports setting `SyslogSpecification`, the options
While the `SyslogParserBuilder` supports setting `SyslogSpecification`, the options
for changing the `AllowableVariations`, the `SyslogSpecifictation` and the `KeyProvider` are set on the
provided `SyslogBuilder` implemenations.

Callers may or may not use these in their `SyslogBuilder` implementations as well.

##### SyslogSpecification

The specifications supported by the library. `RFC_5424`, `RFC_6587_5424`, `RFC_3164`, and `RFC_6587_3164`.
The specifications supported by the library. `RFC_5424`, `RFC_6587_5424`, `RFC_3164`, and `RFC_6587_3164`.

##### AllowableDeviations

Allowable deviations from the specifications. This allows for fields required by the specification, but perhaps
Allowable deviations from the specifications. This allows for fields required by the specification, but perhaps
omitted by convention to be missing, and a line that is by specificiation technically incorrect to still parse.

This is specified by an {@code EnumSet}
Expand Down Expand Up @@ -234,7 +238,8 @@ A custom `KeyProvider` can be supplied to the provided `SyslogBuilder` implemena
Note that the keys are a superset of the syslog specifications.

##### NilPolicy
The `NilPolicy` governs how the parser handles *nil* message parts for `SyslogSpecification.RFC_5424`. That is message parts that can be *nil* as part of a valid message;

The `NilPolicy` governs how the parser handles _nil_ message parts for `SyslogSpecification.RFC_5424`. That is message parts that can be _nil_ as part of a valid message;

- HOSTNAME
- APPNAME
Expand All @@ -250,47 +255,46 @@ The `NilPolicy` governs how the parser handles *nil* message parts for `SyslogSp

The default policy is `OMIT`.


### Creating your own Parsers

Simple Syslog 5424 uses [Antlr 4](http://www.antlr.org) to generate the `Listener` that the parser is based on.
The generated `Rfc5424Listener` and `Rfc5424Visitor` interfaces, or `Rfc5424BaseListener` and `Rfc5424BaseVisitor` classes,
may be used to implement new parsers as well in the event that you prefer different handling.

Implementors would then build their own parsers or builders etc. In other words the use of this library would
Implementors would then build their own parsers or builders etc. In other words the use of this library would
minimally be the Antlr classes alone.

For examples, see the implementations of `Rfc3164SyslogParser` and `Rfc5424SyslogParser` for examples of
parser implementations as well as the `Syslog3164Listener` and `Syslog5424Listener` implementations.

### Building
This project uses [simple-syslog-grammars]( https://github.com/palindromicity/simple-syslog-grammars)

This project uses [simple-syslog-grammars](https://github.com/palindromicity/simple-syslog-grammars)
You will want to use `git clone --recursive` and ensure the src/main/antlr4/com/github/palindromicity/syslog/dsl/generated directory is created.

### Questions

- __*Why not just use [java-grok](https://github.com/thekrakken/java-grok)?*__
- **_Why not just use [java-grok](https://github.com/thekrakken/java-grok)?_**

Though I love java-grok (it is used in [Apache Metron](https://metron.apache.org) and [Apache Nifi](https://nifi.apache.org) which I contribute to), and have even
submitted PRs to it, it and other Regex based parsers do not handle Syslog 5424 Structured Data. I wanted something
that did. I have not found any regex based approach which handles structured data in a single pass. If you find one, let me know!
submitted PRs to it, it and other Regex based parsers do not handle Syslog 5424 Structured Data. I wanted something
that did. I have not found any regex based approach which handles structured data in a single pass. If you find one, let me know!

- __*Why not fix the groks to handle it? Or create regexes outside of grok?*__
- **_Why not fix the groks to handle it? Or create regexes outside of grok?_**

I'm not good enough at regex, and couldn't write something that worked single pass.

- __*Why not write a custom state machine type parser?*__
- **_Why not write a custom state machine type parser?_**

I like Antlr and wanted to try it ;)

--------

---

```xml
<dependency>
<groupId>com.github.palindromicity</groupId>
<artifactId>simple-syslog</artifactId>
<version>1.0.0</version>
<version>VERSION</version>
<type>pom</type>
</dependency>
```
4 changes: 2 additions & 2 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
</developers>
<scm>
<connection>scm:git:https://github.com/palindromicity/simple-syslog.git</connection>
<developerConnection>scm:git:git@github.com:palindromicity/simple-syslog.git</developerConnection>
<developerConnection>scm:git:https://github.com/palindromicity/simple-syslog.git</developerConnection>
<url>https://github.com/palindromicity/simple-syslog</url>
<tag>simple-syslog-1.0.0</tag>
</scm>
Expand All @@ -39,7 +39,7 @@
<properties>
<maven.min-version>3.5.2</maven.min-version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<global_antlr_version>4.7.2</global_antlr_version>
<global_antlr_version>4.13.2</global_antlr_version>
<global_jspecify_version>0.2.0</global_jspecify_version>
</properties>
<distributionManagement>
Expand Down
Loading
Loading