001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache license, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the license for the specific language governing permissions and
015 * limitations under the license.
016 */
017
018package org.apache.logging.log4j.core.appender;
019
020import java.io.Serializable;
021
022import org.apache.logging.log4j.core.Appender;
023import org.apache.logging.log4j.core.Core;
024import org.apache.logging.log4j.core.Filter;
025import org.apache.logging.log4j.core.Layout;
026import org.apache.logging.log4j.core.LogEvent;
027import org.apache.logging.log4j.core.config.Configuration;
028import org.apache.logging.log4j.core.config.DefaultConfiguration;
029import org.apache.logging.log4j.core.config.Property;
030import org.apache.logging.log4j.core.config.plugins.Plugin;
031import org.apache.logging.log4j.core.config.plugins.PluginAttribute;
032import org.apache.logging.log4j.core.config.plugins.PluginConfiguration;
033import org.apache.logging.log4j.core.config.plugins.PluginElement;
034import org.apache.logging.log4j.core.config.plugins.PluginFactory;
035import org.apache.logging.log4j.core.config.plugins.validation.constraints.Required;
036import org.apache.logging.log4j.core.config.plugins.validation.constraints.ValidPort;
037import org.apache.logging.log4j.core.filter.ThresholdFilter;
038import org.apache.logging.log4j.core.layout.HtmlLayout;
039import org.apache.logging.log4j.core.net.SmtpManager;
040import org.apache.logging.log4j.core.util.Booleans;
041
042/**
043 * Send an e-mail when a specific logging event occurs, typically on errors or
044 * fatal errors.
045 *
046 * <p>
047 * The number of logging events delivered in this e-mail depend on the value of
048 * <b>BufferSize</b> option. The <code>SmtpAppender</code> keeps only the last
049 * <code>BufferSize</code> logging events in its cyclic buffer. This keeps
050 * memory requirements at a reasonable level while still delivering useful
051 * application context.
052 *
053 * By default, an email message will formatted as HTML. This can be modified by
054 * setting a layout for the appender.
055 *
056 * By default, an email message will be sent when an ERROR or higher severity
057 * message is appended. This can be modified by setting a filter for the
058 * appender.
059 */
060@Plugin(name = "SMTP", category = Core.CATEGORY_NAME, elementType = Appender.ELEMENT_TYPE, printObject = true)
061public final class SmtpAppender extends AbstractAppender {
062
063    private static final int DEFAULT_BUFFER_SIZE = 512;
064
065    /** The SMTP Manager */
066    private final SmtpManager manager;
067
068    private SmtpAppender(final String name, final Filter filter, final Layout<? extends Serializable> layout,
069            final SmtpManager manager, final boolean ignoreExceptions, final Property[] properties) {
070        super(name, filter, layout, ignoreExceptions, properties);
071        this.manager = manager;
072    }
073
074    /**
075     * Create a SmtpAppender.
076     *
077     * @param name
078     *            The name of the Appender.
079     * @param to
080     *            The comma-separated list of recipient email addresses.
081     * @param cc
082     *            The comma-separated list of CC email addresses.
083     * @param bcc
084     *            The comma-separated list of BCC email addresses.
085     * @param from
086     *            The email address of the sender.
087     * @param replyTo
088     *            The comma-separated list of reply-to email addresses.
089     * @param subject The subject of the email message.
090     * @param smtpProtocol The SMTP transport protocol (such as "smtps", defaults to "smtp").
091     * @param smtpHost
092     *            The SMTP hostname to send to.
093     * @param smtpPortStr
094     *            The SMTP port to send to.
095     * @param smtpUsername
096     *            The username required to authenticate against the SMTP server.
097     * @param smtpPassword
098     *            The password required to authenticate against the SMTP server.
099     * @param smtpDebug
100     *            Enable mail session debuging on STDOUT.
101     * @param bufferSizeStr
102     *            How many log events should be buffered for inclusion in the
103     *            message?
104     * @param layout
105     *            The layout to use (defaults to HtmlLayout).
106     * @param filter
107     *            The Filter or null (defaults to ThresholdFilter, level of
108     *            ERROR).
109     * @param ignore If {@code "true"} (default) exceptions encountered when appending events are logged; otherwise
110     *               they are propagated to the caller.
111     * @return The SmtpAppender.
112     */
113    @PluginFactory
114    public static SmtpAppender createAppender(
115            @PluginConfiguration final Configuration config,
116            @PluginAttribute("name") @Required final String name,
117            @PluginAttribute("to") final String to,
118            @PluginAttribute("cc") final String cc,
119            @PluginAttribute("bcc") final String bcc,
120            @PluginAttribute("from") final String from,
121            @PluginAttribute("replyTo") final String replyTo,
122            @PluginAttribute("subject") final String subject,
123            @PluginAttribute("smtpProtocol") final String smtpProtocol,
124            @PluginAttribute("smtpHost") final String smtpHost,
125            @PluginAttribute(value = "smtpPort", defaultString = "0") @ValidPort final String smtpPortStr,
126            @PluginAttribute("smtpUsername") final String smtpUsername,
127            @PluginAttribute(value = "smtpPassword", sensitive = true) final String smtpPassword,
128            @PluginAttribute("smtpDebug") final String smtpDebug,
129            @PluginAttribute("bufferSize") final String bufferSizeStr,
130            @PluginElement("Layout") Layout<? extends Serializable> layout,
131            @PluginElement("Filter") Filter filter,
132            @PluginAttribute("ignoreExceptions") final String ignore) {
133        if (name == null) {
134            LOGGER.error("No name provided for SmtpAppender");
135            return null;
136        }
137
138        final boolean ignoreExceptions = Booleans.parseBoolean(ignore, true);
139        final int smtpPort = AbstractAppender.parseInt(smtpPortStr, 0);
140        final boolean isSmtpDebug = Boolean.parseBoolean(smtpDebug);
141        final int bufferSize = bufferSizeStr == null ? DEFAULT_BUFFER_SIZE : Integer.parseInt(bufferSizeStr);
142
143        if (layout == null) {
144            layout = HtmlLayout.createDefaultLayout();
145        }
146        if (filter == null) {
147            filter = ThresholdFilter.createFilter(null, null, null);
148        }
149        final Configuration configuration = config != null ? config : new DefaultConfiguration();
150
151        final SmtpManager manager = SmtpManager.getSmtpManager(configuration, to, cc, bcc, from, replyTo, subject, smtpProtocol,
152            smtpHost, smtpPort, smtpUsername, smtpPassword, isSmtpDebug, filter.toString(),  bufferSize);
153        if (manager == null) {
154            return null;
155        }
156
157        return new SmtpAppender(name, filter, layout, manager, ignoreExceptions, null);
158    }
159
160    /**
161     * Capture all events in CyclicBuffer.
162     * @param event The Log event.
163     * @return true if the event should be filtered.
164     */
165    @Override
166    public boolean isFiltered(final LogEvent event) {
167        final boolean filtered = super.isFiltered(event);
168        if (filtered) {
169            manager.add(event);
170        }
171        return filtered;
172    }
173
174    /**
175     * Perform SmtpAppender specific appending actions, mainly adding the event
176     * to a cyclic buffer and checking if the event triggers an e-mail to be
177     * sent.
178     * @param event The Log event.
179     */
180    @Override
181    public void append(final LogEvent event) {
182        manager.sendEvents(getLayout(), event);
183    }
184}