satishy / cloudwatch-logging-spring-boot-starter

Amazon CloudWatch Logging dependency adds ability to automatically sent your log messages to AWS CloudWatch storage

Amazon CloudWatch Logging

Amazon CloudWatch Logging dependency adds ability to automatically sent your log messages to AWS CloudWatch storage. Currently, only support for Logback is present

Workflow

Dependency

Amazon CloudWatch Logging dependency resides at Intapp Artifactory repository, so to pull it your should have valid credentials (please, consult your system administrator if you don't have one yet).

Gradle example

To include this dependency into your Gradle project, please, setup artifactory plugin and specify dependency as follows:

// your configuration

repositories {
    mavenCentral()
    maven {
        url "${artifactory_contextUrl}/${artifactory_repo}"
        credentials {
            username "${artifactory_user}"
            password "${artifactory_password}"
        }
    }
}

dependencies {
    // other dependencies

    // this dependency
    compile group: 'com.intapp.platform', name: 'cloudwatch-logging-spring-boot-starter', version: "$latestAvailableVersion"
}

This artifact is build with and depends on next libraries:

• spring-boot-starter, version: 1.5.3.RELEASE
• aws-java-sdk-logs and aws-java-sdk-cloudwatch, version: 1.11.18
• guava, version: 21.0

If you already have some (or all) of this dependencies in your classpath, you can force Gradle to exclude some (or all) dependencies as follows:

dependencies {
    // other dependencies

    // this exclude AWS dependencies
    compile("com.intapp.platform:cloudwatch-logging-spring-boot-starter:$latestAvailableVersion") {
        exclude group: 'com.amazonaws'
    }
    
    // exclude all transitive dependencies
    compile group: 'com.intapp.platform', name: 'cloudwatch-logging-spring-boot-starter', version: "$latestAvailableVersion", transitive: false
}

Maven example

TBD

Usage

Logback XML configuration

You can specify, that CloudWatch appender should be used for logging in Logback XML configuration file (logback.xml or logback-spring.xml). See example for Spring-based application with profile support:

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true">

    <!-- resolve CloudWatch settings from configuration -->
    <springProperty name="logGroup" source="logging.cloudwatch.log-group"/>
    <springProperty name="logStream" source="logging.cloudwatch.log-stream"/>
    <springProperty name="awsRegion" source="logging.cloudwatch.region"/>
    <springProperty name="logPattern" source="logging.cloudwatch.pattern"/>

    <!-- for dev profile print logs in console -->
    <springProfile name="dev">
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>%d %-5level --- [%15.15thread] %-40.40logger{40} : %msg%n</pattern>
            </encoder>
        </appender>

        <root>
            <appender-ref ref="STDOUT"/>
        </root>
    </springProfile>


    <!-- for cloud profile save logs in CloudWatch -->
    <springProfile name="cloud">
        <!-- appender from this dependency goes here -->
        <appender name="CLOUDWATCH" class="com.intapp.platform.logging.logback.appender.AmazonCloudWatchAppender">
            <region>${awsRegion}</region>
            <logGroup>${logGroup:- }</logGroup>
            <logStream>${logStream:- }</logStream>
            <layout class="ch.qos.logback.classic.PatternLayout">
                <pattern>${logPattern:-%msg%n}</pattern>
            </layout>
        </appender>

        <root>
            <appender-ref ref="CLOUDWATCH"/>
        </root>
    </springProfile>
</configuration>

Main benefit of such approach:

• starts earlier, than two next approaches (as soon as Spring configuration is resolved), so you will be able to see more logs related to application bootstrap
• allows to use full power of Logback configuration

@EnableCloudWatchLogging annotation

Placing @EnableCloudWatchLogging on main class of your application will enable CloudWatch logging for your service in specified profile(s).

@SpringBootApplication
@EnableCloudWatchLogging("production")                  // one profile
@EnableCloudWatchLogging({"cloud", "prod"})             // any of profiles
public class MainApplication {
}

CloudWatch logging can be enabled/disabled via configuration parameter:

logging:
  cloudwatch:
    enabled: false # default value - unspecified (considered as false)

Main benefit of such approach:

• easy to use and enable/disable

Manual bean registration

You can manually create CloudWatchLogbackConfigurationAdapter (or override it) to have more control of logging behavior:

@Autowired  // configure as you wish
private CloudWatchProperties properties;

@Bean
public CloudWatchLogbackConfiguration cloudWatchLogbackConfiguration() {
    return new CloudWatchLogbackConfiguration(properties);
}

Main benefit of such approach:

• control about CloudWatch settings (log-group, log-stream, region, pattern)