001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *      http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    package org.apache.oozie.util;
019    
020    
021    import org.apache.commons.logging.Log;
022    import org.apache.commons.logging.LogFactory;
023    import org.apache.hadoop.fs.FileSystem;
024    import org.apache.hadoop.fs.Path;
025    
026    import java.text.MessageFormat;
027    import java.util.ArrayList;
028    import java.util.HashMap;
029    import java.util.List;
030    import java.util.Map;
031    
032    /**
033     * The <code>XLog</code> class extends the functionality of the Apache common-logging <code>Log</code> interface. <p/>
034     * It provides common prefix support, message templating with variable parameters and selective tee logging to multiple
035     * logs. <p/> It provides also the LogFactory functionality.
036     */
037    public class XLog implements Log {
038    
039        public static final String INSTRUMENTATION_LOG_NAME = "oozieinstrumentation";
040    
041        /**
042         * <code>LogInfo</code> stores contextual information to create log prefixes. <p/> <code>LogInfo</code> uses a
043         * <code>ThreadLocal</code> to propagate the context. <p/> <code>LogInfo</code> context parameters are configurable
044         * singletons.
045         */
046        public static class Info {
047            private static String template = "";
048            private static List<String> parameterNames = new ArrayList<String>();
049    
050            private static ThreadLocal<Info> tlLogInfo = new ThreadLocal<Info>() {
051                @Override
052                protected Info initialValue() {
053                    return new Info();
054                }
055    
056            };
057    
058            /**
059             * Define a <code>LogInfo</code> context parameter. <p/> The parameter name and its contextual value will be
060             * used to create all prefixes.
061             *
062             * @param name name of the context parameter.
063             */
064            public static void defineParameter(String name) {
065                ParamChecker.notEmpty(name, "name");
066                int count = parameterNames.size();
067                if (count > 0) {
068                    template += " ";
069                }
070                template += name + "[{" + count + "}]";
071                parameterNames.add(name);
072            }
073    
074            /**
075             * Remove all defined context parameters. <p/>
076             */
077            public static void reset() {
078                template = "";
079                parameterNames.clear();
080            }
081    
082            /**
083             * Return the <code>LogInfo</code> instance in context.
084             *
085             * @return The thread local instance of LogInfo
086             */
087            public static Info get() {
088                return tlLogInfo.get();
089            }
090    
091            /**
092             * Remove the <code>LogInfo</code> instance in context.
093             */
094            public static void remove() {
095                tlLogInfo.remove();
096            }
097    
098            private Map<String, String> parameters = new HashMap<String, String>();
099    
100            /**
101             * Constructs an empty LogInfo.
102             */
103            public Info() {
104            }
105    
106    
107            /**
108             * Construct a new LogInfo object from an existing one.
109             *
110             * @param logInfo LogInfo object to copy parameters from.
111             */
112            public Info(Info logInfo) {
113                setParameters(logInfo);
114            }
115    
116            /**
117             * Clear all parameters set in this logInfo instance.
118             */
119            public void clear() {
120                parameters.clear();
121            }
122    
123            /**
124             * Set a parameter value in the <code>LogInfo</code> context.
125             *
126             * @param name parameter name.
127             * @param value parameter value.
128             */
129            public void setParameter(String name, String value) {
130                if (!parameterNames.contains(name)) {
131                    throw new IllegalArgumentException(format("Parameter[{0}] not defined", name));
132                }
133                parameters.put(name, value);
134            }
135    
136            /**
137             * Returns the specified parameter.
138             *
139             * @param name parameter name.
140             * @return the parameter value.
141             */
142            public String getParameter(String name) {
143                return parameters.get(name);
144            }
145    
146            /**
147             * Clear a parameter value from the <code>LogInfo</code> context.
148             *
149             * @param name parameter name.
150             */
151            public void clearParameter(String name) {
152                if (!parameterNames.contains(name)) {
153                    throw new IllegalArgumentException(format("Parameter[{0}] not defined", name));
154                }
155                parameters.remove(name);
156            }
157    
158            /**
159             * Set all the parameter values from the given <code>LogInfo</code>.
160             *
161             * @param logInfo <code>LogInfo</code> to copy all parameter values from.
162             */
163            public void setParameters(Info logInfo) {
164                parameters.clear();
165                parameters.putAll(logInfo.parameters);
166            }
167    
168            /**
169             * Create the <code>LogInfo</code> prefix using the current parameter values.
170             *
171             * @return the <code>LogInfo</code> prefix.
172             */
173            public String createPrefix() {
174                String[] params = new String[parameterNames.size()];
175                for (int i = 0; i < params.length; i++) {
176                    params[i] = parameters.get(parameterNames.get(i));
177                    if (params[i] == null) {
178                        params[i] = "-";
179                    }
180                }
181                return MessageFormat.format(template, (Object[]) params);
182            }
183    
184        }
185    
186        /**
187         * Return the named logger configured with the {@link org.apache.oozie.util.XLog.Info} prefix.
188         *
189         * @param name logger name.
190         * @return the named logger configured with the {@link org.apache.oozie.util.XLog.Info} prefix.
191         */
192        public static XLog getLog(String name) {
193            return getLog(name, true);
194        }
195    
196        /**
197         * Return the named logger configured with the {@link org.apache.oozie.util.XLog.Info} prefix.
198         *
199         * @param clazz from which the logger name will be derived.
200         * @return the named logger configured with the {@link org.apache.oozie.util.XLog.Info} prefix.
201         */
202        public static XLog getLog(Class clazz) {
203            return getLog(clazz, true);
204        }
205    
206        /**
207         * Return the named logger.
208         *
209         * @param name logger name.
210         * @param prefix indicates if the {@link org.apache.oozie.util.XLog.Info} prefix has to be used or not.
211         * @return the named logger.
212         */
213        public static XLog getLog(String name, boolean prefix) {
214            return new XLog(LogFactory.getLog(name), (prefix) ? Info.get().createPrefix() : "");
215        }
216    
217        /**
218         * Return the named logger.
219         *
220         * @param clazz from which the logger name will be derived.
221         * @param prefix indicates if the {@link org.apache.oozie.util.XLog.Info} prefix has to be used or not.
222         * @return the named logger.
223         */
224        public static XLog getLog(Class clazz, boolean prefix) {
225            return new XLog(LogFactory.getLog(clazz), (prefix) ? Info.get().createPrefix() : "");
226        }
227    
228        /**
229         * Reset the logger prefix
230         *
231         * @param log the named logger
232         * @return the named logger with reset prefix
233         */
234        public static XLog resetPrefix(XLog log) {
235            log.setMsgPrefix(Info.get().createPrefix());
236            return log;
237        }
238    
239        /**
240         * Mask for logging to the standard log.
241         */
242        public static final int STD = 1;
243    
244        /**
245         * Mask for tee logging to the OPS log.
246         */
247        public static final int OPS = 4;
248    
249        private static final int ALL = STD | OPS;
250    
251        private static final int[] LOGGER_MASKS = {STD, OPS};
252    
253        //package private for testing purposes.
254        Log[] loggers;
255    
256        private String prefix = "";
257    
258        /**
259         * Create a <code>XLog</code> with no prefix.
260         *
261         * @param log Log instance to use for logging.
262         */
263        public XLog(Log log) {
264            this(log, "");
265        }
266    
267        /**
268         * Create a <code>XLog</code> with a common prefix. <p/> The prefix will be prepended to all log messages.
269         *
270         * @param log Log instance to use for logging.
271         * @param prefix common prefix to use for all log messages.
272         */
273        public XLog(Log log, String prefix) {
274            this.prefix = prefix;
275            loggers = new Log[2];
276            loggers[0] = log;
277            loggers[1] = LogFactory.getLog("oozieops");
278        }
279    
280        /**
281         * Return the common prefix.
282         *
283         * @return the common prefix.
284         */
285        public String getMsgPrefix() {
286            return prefix;
287        }
288    
289        /**
290         * Set the common prefix.
291         *
292         * @param prefix the common prefix to set.
293         */
294        public void setMsgPrefix(String prefix) {
295            this.prefix = (prefix != null) ? prefix : "";
296        }
297    
298        //All the methods from the commonsLogging Log interface will log to the default logger only.
299    
300        /**
301         * Log a debug message to the common <code>Log</code>.
302         *
303         * @param o message.
304         */
305        @Override
306        public void debug(Object o) {
307            log(Level.DEBUG, STD, "{0}", o);
308        }
309    
310        /**
311         * Log a debug message and <code>Exception</code> to the common <code>Log</code>.
312         *
313         * @param o message.
314         * @param throwable exception.
315         */
316        @Override
317        public void debug(Object o, Throwable throwable) {
318            log(Level.DEBUG, STD, "{0}", o, throwable);
319        }
320    
321        /**
322         * Log a error message to the common <code>Log</code>.
323         *
324         * @param o message.
325         */
326        @Override
327        public void error(Object o) {
328            log(Level.ERROR, STD, "{0}", o);
329        }
330    
331        /**
332         * Log a error message and <code>Exception</code> to the common <code>Log</code>.
333         *
334         * @param o message.
335         * @param throwable exception.
336         */
337        @Override
338        public void error(Object o, Throwable throwable) {
339            log(Level.ERROR, STD, "{0}", o, throwable);
340        }
341    
342        /**
343         * Log a fatal message to the common <code>Log</code>.
344         *
345         * @param o message.
346         */
347        @Override
348        public void fatal(Object o) {
349            log(Level.FATAL, STD, "{0}", o);
350        }
351    
352        /**
353         * Log a fatal message and <code>Exception</code> to the common <code>Log</code>.
354         *
355         * @param o message.
356         * @param throwable exception.
357         */
358        @Override
359        public void fatal(Object o, Throwable throwable) {
360            log(Level.FATAL, STD, "{0}", o, throwable);
361        }
362    
363        /**
364         * Log a info message to the common <code>Log</code>.
365         *
366         * @param o message.
367         */
368        @Override
369        public void info(Object o) {
370            log(Level.INFO, STD, "{0}", o);
371        }
372    
373        /**
374         * Log a info message and <code>Exception</code> to the common <code>Log</code>.
375         *
376         * @param o message.
377         * @param throwable exception.
378         */
379        @Override
380        public void info(Object o, Throwable throwable) {
381            log(Level.INFO, STD, "{0}", o, throwable);
382        }
383    
384        /**
385         * Log a trace message to the common <code>Log</code>.
386         *
387         * @param o message.
388         */
389        @Override
390        public void trace(Object o) {
391            log(Level.TRACE, STD, "{0}", o);
392        }
393    
394        /**
395         * Log a trace message and <code>Exception</code> to the common <code>Log</code>.
396         *
397         * @param o message.
398         * @param throwable exception.
399         */
400        @Override
401        public void trace(Object o, Throwable throwable) {
402            log(Level.TRACE, STD, "{0}", o, throwable);
403        }
404    
405        /**
406         * Log a warn message to the common <code>Log</code>.
407         *
408         * @param o message.
409         */
410        @Override
411        public void warn(Object o) {
412            log(Level.WARN, STD, "{0}", o);
413        }
414    
415        /**
416         * Log a warn message and <code>Exception</code> to the common <code>Log</code>.
417         *
418         * @param o message.
419         * @param throwable exception.
420         */
421        @Override
422        public void warn(Object o, Throwable throwable) {
423            log(Level.WARN, STD, "{0}", o, throwable);
424        }
425    
426        /**
427         * Return if debug logging is enabled.
428         *
429         * @return <code>true</code> if debug logging is enable, <code>false</code> if not.
430         */
431        @Override
432        public boolean isDebugEnabled() {
433            return isEnabled(Level.DEBUG, ALL);
434        }
435    
436        /**
437         * Return if error logging is enabled.
438         *
439         * @return <code>true</code> if error logging is enable, <code>false</code> if not.
440         */
441        @Override
442        public boolean isErrorEnabled() {
443            return isEnabled(Level.ERROR, ALL);
444        }
445    
446        /**
447         * Return if fatal logging is enabled.
448         *
449         * @return <code>true</code> if fatal logging is enable, <code>false</code> if not.
450         */
451        @Override
452        public boolean isFatalEnabled() {
453            return isEnabled(Level.FATAL, ALL);
454        }
455    
456        /**
457         * Return if info logging is enabled.
458         *
459         * @return <code>true</code> if info logging is enable, <code>false</code> if not.
460         */
461        @Override
462        public boolean isInfoEnabled() {
463            return isEnabled(Level.INFO, ALL);
464        }
465    
466        /**
467         * Return if trace logging is enabled.
468         *
469         * @return <code>true</code> if trace logging is enable, <code>false</code> if not.
470         */
471        @Override
472        public boolean isTraceEnabled() {
473            return isEnabled(Level.TRACE, ALL);
474        }
475    
476        /**
477         * Return if warn logging is enabled.
478         *
479         * @return <code>true</code> if warn logging is enable, <code>false</code> if not.
480         */
481        @Override
482        public boolean isWarnEnabled() {
483            return isEnabled(Level.WARN, ALL);
484        }
485    
486        public enum Level {
487            FATAL, ERROR, INFO, WARN, DEBUG, TRACE
488        }
489    
490        private boolean isEnabled(Level level, int loggerMask) {
491            for (int i = 0; i < loggers.length; i++) {
492                if ((LOGGER_MASKS[i] & loggerMask) != 0) {
493                    boolean enabled = false;
494                    switch (level) {
495                        case FATAL:
496                            enabled = loggers[i].isFatalEnabled();
497                            break;
498                        case ERROR:
499                            enabled = loggers[i].isErrorEnabled();
500                            break;
501                        case INFO:
502                            enabled = loggers[i].isInfoEnabled();
503                            break;
504                        case WARN:
505                            enabled = loggers[i].isWarnEnabled();
506                            break;
507                        case DEBUG:
508                            enabled = loggers[i].isDebugEnabled();
509                            break;
510                        case TRACE:
511                            enabled = loggers[i].isTraceEnabled();
512                            break;
513                    }
514                    if (enabled) {
515                        return true;
516                    }
517                }
518            }
519            return false;
520        }
521    
522    
523        private void log(Level level, int loggerMask, String msgTemplate, Object... params) {
524            loggerMask |= STD;
525            if (isEnabled(level, loggerMask)) {
526                String prefix = getMsgPrefix();
527                prefix = (prefix != null && prefix.length() > 0) ? prefix + " " : "";
528    
529                String msg = prefix + format(msgTemplate, params);
530                Throwable throwable = getCause(params);
531    
532                for (int i = 0; i < LOGGER_MASKS.length; i++) {
533                    if (isEnabled(level, loggerMask & LOGGER_MASKS[i])) {
534                        Log log = loggers[i];
535                        switch (level) {
536                            case FATAL:
537                                log.fatal(msg, throwable);
538                                break;
539                            case ERROR:
540                                log.error(msg, throwable);
541                                break;
542                            case INFO:
543                                log.info(msg, throwable);
544                                break;
545                            case WARN:
546                                log.warn(msg, throwable);
547                                break;
548                            case DEBUG:
549                                log.debug(msg, throwable);
550                                break;
551                            case TRACE:
552                                log.trace(msg, throwable);
553                                break;
554                        }
555                    }
556                }
557            }
558        }
559    
560        /**
561         * Log a fatal message <code>Exception</code> to the common <code>Log</code>.
562         *
563         * @param msgTemplate message template.
564         * @param params parameters for the message template. If the last parameter is an exception it is logged as such.
565         */
566        public void fatal(String msgTemplate, Object... params) {
567            log(Level.FATAL, STD, msgTemplate, params);
568        }
569    
570        /**
571         * Log a error message <code>Exception</code> to the common <code>Log</code>.
572         *
573         * @param msgTemplate message template.
574         * @param params parameters for the message template. If the last parameter is an exception it is logged as such.
575         */
576        public void error(String msgTemplate, Object... params) {
577            log(Level.ERROR, STD, msgTemplate, params);
578        }
579    
580        /**
581         * Log a info message <code>Exception</code> to the common <code>Log</code>.
582         *
583         * @param msgTemplate message template.
584         * @param params parameters for the message template. If the last parameter is an exception it is logged as such.
585         */
586        public void info(String msgTemplate, Object... params) {
587            log(Level.INFO, STD, msgTemplate, params);
588        }
589    
590        /**
591         * Log a warn message <code>Exception</code> to the common <code>Log</code>.
592         *
593         * @param msgTemplate message template.
594         * @param params parameters for the message template. If the last parameter is an exception it is logged as such.
595         */
596        public void warn(String msgTemplate, Object... params) {
597            log(Level.WARN, STD, msgTemplate, params);
598        }
599    
600        /**
601         * Log a debug message <code>Exception</code> to the common <code>Log</code>.
602         *
603         * @param msgTemplate message template.
604         * @param params parameters for the message template. If the last parameter is an exception it is logged as such.
605         */
606        public void debug(String msgTemplate, Object... params) {
607            log(Level.DEBUG, STD, msgTemplate, params);
608        }
609    
610        /**
611         * Log a trace message <code>Exception</code> to the common <code>Log</code>.
612         *
613         * @param msgTemplate message template.
614         * @param params parameters for the message template. If the last parameter is an exception it is logged as such.
615         */
616        public void trace(String msgTemplate, Object... params) {
617            log(Level.TRACE, STD, msgTemplate, params);
618        }
619    
620        /**
621         * Tee Log a fatal message <code>Exception</code> to the common log and specified <code>Log</code>s.
622         *
623         * @param loggerMask log mask, it is a bit mask, possible values are <code>APP</code> and <code>OPS</code>.
624         * @param msgTemplate message template.
625         * @param params parameters for the message template.
626         */
627        public void fatal(int loggerMask, String msgTemplate, Object... params) {
628            log(Level.FATAL, loggerMask, msgTemplate, params);
629        }
630    
631        /**
632         * Tee Log a error message <code>Exception</code> to the common log and specified <code>Log</code>s.
633         *
634         * @param loggerMask log mask, it is a bit mask, possible values are <code>APP</code> and <code>OPS</code>.
635         * @param msgTemplate message template.
636         * @param params parameters for the message template.
637         */
638        public void error(int loggerMask, String msgTemplate, Object... params) {
639            log(Level.ERROR, loggerMask, msgTemplate, params);
640        }
641    
642        /**
643         * Tee Log a info message <code>Exception</code> to the common log and specified <code>Log</code>s.
644         *
645         * @param loggerMask log mask, it is a bit mask, possible values are <code>APP</code> and <code>OPS</code>.
646         * @param msgTemplate message template.
647         * @param params parameters for the message template.
648         */
649        public void info(int loggerMask, String msgTemplate, Object... params) {
650            log(Level.INFO, loggerMask, msgTemplate, params);
651        }
652    
653        /**
654         * Tee Log a warn message <code>Exception</code> to the common log and specified <code>Log</code>s.
655         *
656         * @param loggerMask log mask, it is a bit mask, possible values are <code>APP</code> and <code>OPS</code>.
657         * @param msgTemplate message template.
658         * @param params parameters for the message template.
659         */
660        public void warn(int loggerMask, String msgTemplate, Object... params) {
661            log(Level.WARN, loggerMask, msgTemplate, params);
662        }
663    
664        /**
665         * Tee Log a debug message <code>Exception</code> to the common log and specified <code>Log</code>s.
666         *
667         * @param loggerMask log mask, it is a bit mask, possible values are <code>APP</code> and <code>OPS</code>.
668         * @param msgTemplate message template.
669         * @param params parameters for the message template.
670         */
671        public void debug(int loggerMask, String msgTemplate, Object... params) {
672            log(Level.DEBUG, loggerMask, msgTemplate, params);
673        }
674    
675        /**
676         * Tee Log a trace message <code>Exception</code> to the common log and specified <code>Log</code>s.
677         *
678         * @param loggerMask log mask, it is a bit mask, possible values are <code>APP</code> and <code>OPS</code>.
679         * @param msgTemplate message template.
680         * @param params parameters for the message template.
681         */
682        public void trace(int loggerMask, String msgTemplate, Object... params) {
683            log(Level.TRACE, loggerMask, msgTemplate, params);
684        }
685    
686        /**
687         * Utility method that does uses the <code>StringFormat</code> to format the message template using the provided
688         * parameters. <p/> In addition to the <code>StringFormat</code> syntax for message templates, it supports
689         * <code>{E}</code> for ENTER. <p/> The last parameter is ignored for the formatting if it is an Exception.
690         *
691         * @param msgTemplate message template.
692         * @param params paramaters to use in the template. If the last parameter is an Exception, it is ignored.
693         * @return formatted message.
694         */
695        public static String format(String msgTemplate, Object... params) {
696            ParamChecker.notEmpty(msgTemplate, "msgTemplate");
697            msgTemplate = msgTemplate.replace("{E}", System.getProperty("line.separator"));
698            if (params != null && params.length > 0) {
699                msgTemplate = MessageFormat.format(msgTemplate, params);
700            }
701            return msgTemplate;
702        }
703    
704        /**
705         * Utility method that extracts the <code>Throwable</code>, if present, from the parameters.
706         *
707         * @param params parameters.
708         * @return a <code>Throwable</code> instance if it is the last parameter, <code>null</code> otherwise.
709         */
710        public static Throwable getCause(Object... params) {
711            Throwable throwable = null;
712            if (params != null && params.length > 0 && params[params.length - 1] instanceof Throwable) {
713                throwable = (Throwable) params[params.length - 1];
714            }
715            return throwable;
716        }
717    
718    }