Developers Notification

Java library which provides developers notification via messengers

Introduction

Sometimes every developer needs to know about the event that happened as soon as possible. For example, about irregular work of the server or about changing the third-party rest-api, about anything, depending on the specifics of the project.

There are many ways to inform developers about such events - all sorts of services, loggers. But most of them send notifications to the mail or a issue tracking system of a different type, which is not always convenient and not always possible to track quickly.

This library sending notifications to messengers. Just create and connect a bot in the messenger that your team using and that is supported by this library. For now it is Slack and Telegram. Add the library to the project, add it configuration (access keys to the bot that you created), add lines, where it is needed, to send message or logging appender and you receive messages when something happened.

Also, this library have monitoring module. It can monitoring current usage of ram and disk memory, set limits of their use and in case of overspending - informs in the selected messengers.

This library compatible with Java 6+

Download

↓ v0.3.0 JAR

The source code to the developers-notification, its samples, and this website is available on GitHub.

Gradle:

                    compile 'com.github.fedorchuck:developers-notification:0.3.0'

Another versions and their JAR-files you can find here.

Setup

Environment configuration

The library is configured by environment variables or system properties. Supported variable is DN. It is single environment variable witch required if you use this library. Accepted value is JSON: 

{
	"messenger": [{
		"name": "SLACK",
		"token": "SLACK_TOKEN",
		"channel": "SLACK_CHANNEL"
	}, {
		"name": "TELEGRAM",
		"token": "TELEGRAM_TOKEN",
		"channel": "TELEGRAM_CHANNEL"
	}],
	"show_whole_log_details": true,
	"protection_from_spam": true,
	"project_name": "Where this library will be invoked",
	"connect_timeout": 5000,
	"user_agent": "Mozilla/5.0",
	"monitoring": {
		"period": 5,
		"unit": "seconds",
		"max_ram": 90,
		"max_disk": 90,
		"disk_consumption_rate": 2
	}
}

  • messenger it is array of objects with configure part of messages destination; required;

    • name contains name of integration. Now available: SLACK and TELEGRAM;

    • token contains token of integration;

    • channel contains channel of integration;

    Note: If you specify several available messengers, you will be received a messages to all specified instant messengers.

  • show_whole_log_details receive boolean value; if value is true - at log will be printed Information containing passwords; is not required; default value is false;

  • protection_from_spam receive boolean value; if value is true - you will be protected from spam (received the same messages each second). It is necessary for adjust the frequency of sending messages; is not required; default value is false;

  • project_name where this library will be invoked; required;

  • connect_timeout for HttpClient is not required; default value is 5000;

  • user_agent user agent for HttpClient is not required; default value is Mozilla/5.0;

  • monitoring it is object with configure part of monitoring current usage of ram and disk memory, set limits of their use and in case of overspending - informs in the selected messengers; required if you use this function;

    • period receive integer value; the frequency with which the monitoring will be carried out;

    • unit the designation in which units the period is measured; should be:

      • SECONDS
      • MINUTES
      • HOURS
      • DAYS

    • max_ram receive integer value; determines the permissible limit of use ram in percent;

    • max_disk receive integer value; determines the permissible limit of use disk in percent;

    • disk_consumption_rate receive integer value; determines the permissible limit of disk consumption rate in percent;

Logging appender

If you want routing some logging level messages to messengers, you should configure this part of project. If you use log4j - your log4j.properties file should contain rows like this: 

# Define the root logger with appender DevelopersNotificationAppender
log4j.rootLogger = DEBUG, DNAppender

# Define the DevelopersNotificationAppender appender
log4j.appender.DNAppender=com.github.fedorchuck.developers_notification.DevelopersNotificationAppender

log4j.appender.DNAppender.Level=ERROR
log4j.appender.DNAppender.layout=org.apache.log4j.PatternLayout
log4j.appender.DNAppender.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} [%c{1}] %5p - %m%n

Note: If you specify unknown logging level, you will recive all logging events to all specified messengers.

Connecting your bot

Slack

  1. Login in into Slack

  2. Add incoming-webhook

  3. Choose a channel and add press green button :-)

  4. Choose the channel again add press green button, again :-)

  5. Find the Integration Settings section

  6. Find the Webhook URL sub-section and copy token. Example url: https://hooks.slack.com/services/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 token: TZXG2L132/B56Z6RGR1/AdlsZzn1QGfo2qrEK4jpO4wJ

  7. Messenger configuration to your project should seems like this:

    {
    "name": "SLACK",
    "token": "TZXG2L132/B56Z6RGR1/AdlsZzn1QGfo2qrEK4jpO4wJ",
    "channel": "general"
}

Telegram

  1. Create your bot

  2. Add the Telegram BOT to your chat.

  3. Get the list of updates for your BOT:

    GET https://api.telegram.org/botYourBOTToken/getUpdates

    example:

    GET https://api.telegram.org/bot32031087:pabzcu_j17-jbd78sadvbdy63d37gda37-d8/getUpdates

  4. Find object chat. It looks like this:

    "chat": {
    "id": -197235129,
    "title": "test group developers notification",
    "type": "group",
    "all_members_are_administrators": true
},

  5. Messenger configuration to your project should seems like this:

    {
    "name": "TELEGRAM",
    "token": "32031087:pabzcu_j17-jbd78sadvbdy63d37gda37-d8",
    "channel": "-197235129"
}

Available methods

You can set needed environment variables using:

DevelopersNotificationUtil.setEnvironmentVariable(key, value);

For checking set environment variables which needed this library use:

DevelopersNotification.printConfiguration();

Note: If configuration value of field show_whole_log_details is false - will be printed result of method Config#getPublicToString()

For sending message to chosen destination you can use methods:

  1. Messenger, spam protection and project name will be reading from config.

    DevelopersNotification.send(
    description,
    throwable
);
    		 
    DevelopersNotification.send(
    "short description",
    new IllegalStateException("abcd")
);

  2. Messenger and spam protection will be reading from config.

    DevelopersNotification.send(
    projectName,
    description,
    throwable
);
    		 
    DevelopersNotification.send(
    "your project name",
    "short description",
    new IllegalStateException("abcd")
);

  3. Spam protection will be reading from config.

    DevelopersNotification.send(
    messengerDestination,
    projectName,
    description,
    throwable
);
    		 
    DevelopersNotification.send(
DevelopersNotificationMessenger.ALL_AVAILABLE,
    "your project name",
    "short description",
    new IllegalStateException("abcd")
);

  4. Messenger will be reading from config.

    DevelopersNotification.send(
    protectionFromSpam,
    projectName,
    description,
    throwable
);
    		 
    DevelopersNotification.send(
    true,
    "your project name",
    "short description",
    new IllegalStateException("abcd")
);

For monitoring current usage of ram and disk memory and in case of overspending limits of their use - get messages in the selected messengers, you can use methods:

  1. Launches monitoring process for current application.

    DevelopersNotification.monitoringStart();

  2. Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted. Invocation has no additional effect if already shut down.

    DevelopersNotification.monitoringStop();

  3. Check if the monitoring thread is alive. A thread is alive if it has been started and has not yet died.

    DevelopersNotification.isMonitoringStateAlive();

Usage

After setup, just insert line in your code, for example:

        try {
            // Your code
        } catch (Exception ex) {
            DevelopersNotification.send("example of usage", ex);
        }

Also, you can use logger appender. Just send message into logger with logging level, which you specified in log configuration and you receive message into specified messenger.

Archive and Javadoc

Version Link to Javadoc Link to Repository
v0.3.0 javadoc JAR-files
v0.2.2 javadoc JAR-files
v0.2.1 javadoc JAR-files
v0.2.0 javadoc JAR-files
v0.1.2 javadoc JAR-files
v0.1.1 javadoc JAR-files
v0.1.0 javadoc JAR-files

License

This software is licensed under Apache License 2.0 

        Copyright 2017 Volodymyr Fedorchuk vl.fedorchuck@gmail.com
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at

            http://www.apache.org/licenses/LICENSE-2.0

        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.