https://github.com/link-nv/logback-s3-rolling-policy
Logback RollingPolicy to store logs in S3
https://github.com/link-nv/logback-s3-rolling-policy
logback logback-rolling-policy s3-bucket
Last synced: 4 months ago
JSON representation
Logback RollingPolicy to store logs in S3
- Host: GitHub
- URL: https://github.com/link-nv/logback-s3-rolling-policy
- Owner: link-nv
- License: apache-2.0
- Created: 2015-07-14T09:03:08.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2025-10-03T10:30:30.000Z (8 months ago)
- Last Synced: 2025-10-03T12:25:00.441Z (8 months ago)
- Topics: logback, logback-rolling-policy, s3-bucket
- Language: Shell
- Size: 366 KB
- Stars: 34
- Watchers: 7
- Forks: 41
- Open Issues: 208
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
Logback RollingPolicy with S3 upload
====================================
logback-s3-rolling-policy automatically uploads rolled log files to S3.
There are 2 rolling policies which can be used:
* `S3FixedWindowRollingPolicy`
* `S3TimeBasedRollingPolicy`
logback-s3-rolling-policy was forked from logback-s3 (https://github.com/shuwada/logback-s3) but transfered into a new project because changes were getting too big.
Index
-----
* [Requirements](#requirements)
* [Usage](#usage)
* [Configuration](#configuration)
* [logback.xml variables](#logbackxml-variables)
* [web.xml](#webxml)
* [logback.xml rolling policy examples](#logbackxml-rolling-policy-examples)
* [AWS Credentials](#aws-credentials)
* [Libraries](#libraries)
Requirements
------------
* Java 1.7+
Configuration
-------------
### logback.xml variables
Whether you implement one of any available S3 policies, the following extra variables (on top of Logback's) can be used:
* `s3BucketName` The S3 bucket name to upload your log files to (mandatory).
* `awsAccessKey` Your AWS access key. If not provided it falls back to the AWS SDK default provider chain.
* `awsSecretKey` Your AWS secret key. If not provided it falls back to the AWS SDK default provider chain.
* `s3FolderName` The S3 folder name in your S3 bucket to put the log files in. This variable supports dates, just put your [pattern](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html) between `%d{}`. Example: `%d{yyyy/MM/dd}`.
* `shutdownHookType` Defines which type of shutdown hook you want to use. This variable is mandatory when you use `rolloverOnExit`. Defaults to `NONE`. Possible values are:
* `NONE` This will not add a shutdown hook. Please note that your most up to date log file won't be uploaded to S3!
* `JVM_SHUTDOWN_HOOK` This will add a runtime shutdown hook. If you're using a webapplication, please use the `SERVLET_CONTEXT`, as the JVM shutdown hook is not really safe to use here.
* `SERVLET_CONTEXT` This will register a shutdown hook to the context destroyed method of `RollingPolicyContextListener`. Don't forget to actually add the context listener to you `web.xml`. (see below)
* `rolloverOnExit` Whether to rollover when your application is being shut down or not. Boolean value, defaults to `false`. If this is set to `false`, and you have defined a `shutdownHookType`, then the log file will be uploaded as is.
* `prefixTimestamp` Whether to prefix the uploaded filename with a timestamp formatted as `yyyyMMdd_HHmmss` or not. Boolean value, defaults to `false`.
* `prefixIdentifier` Whether to prefix the uploaded filename with an identifier or not. Boolean value, defaults to `false`. If running on an AWS EC2 instance, the instance ID will be used. If not running on an AWS EC2 instance, the hostname address will be used. If the hostname address can't be used, a UUID will be used.
### web.xml
If you're using the shutdown hook `SERVLET_CONTEXT` as defined above, you'll need to add the context listener class to your `web.xml`:
```xml
ch.qos.logback.core.rolling.shutdown.RollingPolicyContextListener
```
### Run-time variables
As of version `1.3` you can set run-time variables. For now you can only add an extra S3 folder.
Just use `CustomData.extraS3Folder.set( "extra_folder_name" );` somewhere in your code before the upload occurs. You can always change this value during run-time and it will be picked up on the next upload. set to `null` to ignore.
### logback.xml rolling policy examples
An example `logback.xml` appender for each available policy using `RollingFileAppender`.
* `ch.qos.logback.core.rolling.S3FixedWindowRollingPolicy`:
```xml
logs/myapp.log
[%d] %-8relative %22c{0} [%-5level] %msg%xEx{3}%n
logs/myapp.%i.log.gz
ACCESS_KEY
SECRET_KEY
myapp-logging
logs/%d{yyyy/MM/dd}
true
SERVLET_CONTEXT
true
true
10MB
```
In this example you'll find the logs at `myapp-logging/logs/2015/08/18/`.
* `ch.qos.logback.core.rolling.S3TimeBasedRollingPolicy`:
```xml
logs/myapp.log
[%d] %-8relative %22c{0} [%-5level] %msg%xEx{3}%n
logs/myapp.%d{yyyy-MM-dd_HH-mm}.%i.log.gz
ACCESS_KEY
SECRET_KEY
myapp-logging
log
true
SERVLET_CONTEXT
false
true
10MB
```
In this example you'll find the logs at `myapp-logging/log/`.
### AWS Credentials
It is a good idea to create an IAM user only allowed to upload S3 object to a specific S3 bucket.
It improves the control and reduces the risk of unauthorized access to your S3 bucket.
The following is an example IAM policy.
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:PutObject"
],
"Sid": "Stmt1378251801000",
"Resource": [
"arn:aws:s3:::myapp-logging/log/*"
],
"Effect": "Allow"
}
]
}
```
Libraries
---------
This project uses the following libraries:
* `com.amazonaws:aws-java-sdk:1.11.7`
* `ch.qos.logback:logback-classic:1.2.3`
* `com.google.guava:guava:18.0`
* `javax.servlet:servlet-api:2.4` (scope provided)
* `org.jetbrains:annotations:15.0` (scope provided)