no.nordicsemi.android.log

Class Logger

java.lang.Object

no.nordicsemi.android.log.Logger

public class Logger
extends java.lang.Object

Logger helper class. Makes the logger operations easy. Application needs to have no.nordicsemi.android.LOG permission to use this logger.

To use a logger you must first create a logger session. Log entries can be then appended to the session. Session has 2 parameters: a non-changeable key, which can be e.g. a device address and a name, which can be a human readable device name. nRF Logger application use the key to group devices together. The logger session contains also the application name + optionally a profile name. To create the session invoke newSession(Context, String, String, String) method.

Log entries may not be deleted from the database except by removing the whole session.

Usage:

Adding log entry:

 LogSession session = Logger.newSession(this, "DFU", deviceAddress, deviceName);
 Logger.i(session, "Log session has been created");
 ...
 String error = e.getMessage();
 Logger.e(session, R.string.error_message, error);
 

where in strings.xml there is:

 <string name="error_message">An error occurred: %s</string>
 

Getting session log entries:

 final Cursor c = getContentResolver().query(session.getSessionEntriesUri(), new String[] {
        LogContract.LogColumns.TIME,
        LogContract.LogColumns.LEVEL,
        LogContract.LogColumns.DATA }, null, null, LogContract.LogColumns.TIME + " ASC");
 try {
        while (c.moveToNext()) {
                final String data = c.getString(2 /* DATA */);
                ...
    }
 } finally {
        c.close();
 }
 

You may use the following Uris to perform operations on the data set:

• no.nordicsemi.android.log/application - returns all applications that has created at least one log session
• no.nordicsemi.android.log/application/[APP_ID] - returns all sessions from given application
• no.nordicsemi.android.log/session - returns all sessions
• no.nordicsemi.android.log/session/[SESSION_ID] - returns the session with given id
• no.nordicsemi.android.log/session/[SESSION_ID]/log - returns the log entries from the session with given id
• no.nordicsemi.android.log/session/key/[KEY] - returns all sessions with given key
• no.nordicsemi.android.log/session/key/[KEY]/[NUMBER] - returns the session with given key and number. Numbers starts from 1 for every key.
• no.nordicsemi.android.log/session/key/[KEY]/[NUMBER]/log - returns the log entries from the session with given key and number

Please use LogContract member classes to build Uris.

For every log session created on a new day for a single application (and optionally profile) a special "date" session is created. It's number is equal to 0 and key to "!date". To obtain a list of non-date sessions for a given application id sorted by date, key and time use:

 @Override
 public Loader<Cursor> onCreateLoader(int id, Bundle args) {
        long appId = args.getLong(APPLICATION_ID);

        Uri sessionsUri = LogContract.Session.createSessionsUri(appId);
        String selection = LogContract.Session.NUMBER + ">0";
        return new CursorLoader(this, sessionsUri,
                new String[] { LogContract.SessionColumns.NAME, LogContract.SessionColumns.CREATED_AT },
                selection, null, "date((" + LogContract.SessionColumns.CREATED_AT + " / 1000), 'unixepoch') DESC,
                " + LogContract.SessionColumns.KEY + " ASC,
                " + LogContract.SessionColumns.CREATED_AT + " DESC");
 }
 

Field Summary

Fields

Modifier and Type	Field and Description
static int	MARK_CLEAR
static int	MARK_FLAG_BLUE
static int	MARK_FLAG_RED
static int	MARK_FLAG_YELLOW
static int	MARK_STAR_BLUE
static int	MARK_STAR_RED
static int	MARK_STAR_YELLOW

Constructor Summary

Constructors

Constructor and Description
Logger()

Method Summary

Modifier and Type	Method and Description
static void	a(ILogSession session, int messageResId, java.lang.Object... params) Logs the message in APPLICATION level.
static void	a(ILogSession session, java.lang.String message) Logs the message in APPLICATION level.
static void	d(ILogSession session, int messageResId, java.lang.Object... params) Logs the message in DEBUG (lowest) level.
static void	d(ILogSession session, java.lang.String message) Logs the message in DEBUG (lowest) level.
static void	e(ILogSession session, int messageResId, java.lang.Object... params) Logs the message in ERROR (highest) level.
static void	e(ILogSession session, java.lang.String message) Logs the message in ERROR (highest) level.
static void	i(ILogSession session, int messageResId, java.lang.Object... params) Logs the message in INFO level.
static void	i(ILogSession session, java.lang.String message) Logs the message in INFO level.
static void	log(ILogSession session, android.content.ContentValues[] values) Inserts an array of log entries in a bulk insert operation.
static void	log(ILogSession session, int level, int messageResId, java.lang.Object... params) Adds the log entry to nRF Logger log.
static void	log(ILogSession session, int level, java.lang.String message) Adds the log entry to nRF Logger log.
static void	log(ILogSession session, java.util.List<android.content.ContentValues> values) Inserts a list of log entries in a bulk insert operation.
static android.content.ContentValues	logEntry(ILogSession session, int level, int messageResId, java.lang.Object... params) Returns the log entry.
static android.content.ContentValues	logEntry(ILogSession session, int level, java.lang.String message) Returns the log entry.
static LogSession	newSession(android.content.Context context, java.lang.String key, java.lang.String name) Creates new logger session.
static LogSession	newSession(android.content.Context context, java.lang.String profile, java.lang.String key, java.lang.String name) Creates new logger session.
static ILogSession	openSession(android.content.Context context, android.net.Uri uri) Returns the log session object.
static void	setSessionDescription(LogSession session, java.lang.String description) Sets the session description.
static void	setSessionMark(LogSession session, int mark) Sets the session mark (star or flag).
static void	v(ILogSession session, int messageResId, java.lang.Object... params) Logs the message in VERBOSE level.
static void	v(ILogSession session, java.lang.String message) Logs the message in VERBOSE level.
static void	w(ILogSession session, int messageResId, java.lang.Object... params) Logs the message in WARNING level.
static void	w(ILogSession session, java.lang.String message) Logs the message in WARNING level.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MARK_CLEAR

public static final int MARK_CLEAR

See Also:

Constant Field Values

MARK_STAR_YELLOW

public static final int MARK_STAR_YELLOW

See Also:

Constant Field Values

MARK_STAR_BLUE

public static final int MARK_STAR_BLUE

See Also:

Constant Field Values

MARK_STAR_RED

public static final int MARK_STAR_RED

See Also:

Constant Field Values

MARK_FLAG_YELLOW

public static final int MARK_FLAG_YELLOW

See Also:

Constant Field Values

MARK_FLAG_BLUE

public static final int MARK_FLAG_BLUE

See Also:

Constant Field Values

MARK_FLAG_RED

public static final int MARK_FLAG_RED

See Also:

Constant Field Values

Constructor Detail

Logger

public Logger()

Method Detail

newSession

@Nullable
public static LogSession newSession(@NonNull
                                              android.content.Context context,
                                              @NonNull
                                              java.lang.String key,
                                              @Nullable
                                              java.lang.String name)

Creates new logger session. Must be created before appending log entries. If the nRF Logger application is not installed the method will return null.

Parameters:

context - the context (activity, service or application).

key - the session key, which is used to group sessions.

name - the human readable session name.

Returns:

The LogSession that can be used to append log entries or null if nRF Logger is not installed. The null value can be next passed to logging methods.

newSession

@Nullable
public static LogSession newSession(@NonNull
                                              android.content.Context context,
                                              @Nullable
                                              java.lang.String profile,
                                              @NonNull
                                              java.lang.String key,
                                              @Nullable
                                              java.lang.String name)

Creates new logger session. Must be created before appending log entries. If the nRF Logger application is not installed the method will return null.

Parameters:

context - the context (activity, service or application).

profile - application profile which will be concatenated to the application name.

key - the session key, which is used to group sessions.

name - the human readable session name.

Returns:

The LogSession that can be used to append log entries or null if nRF Logger is not installed. The null value can be next passed to logging methods.

openSession

@Nullable
public static ILogSession openSession(@NonNull
                                                android.content.Context context,
                                                @Nullable
                                                android.net.Uri uri)

Returns the log session object. The given Uri must points session log entries: .../session/#, .../session/[KEY]/[NUMBER], or both with ./log appended. For Uris not matching these patterns a LocalLogSession object will be created.

Parameters:

context - the application context.

uri - the session uri.

Returns:

The log session, or null.

setSessionDescription

public static void setSessionDescription(@Nullable
                                         LogSession session,
                                         @Nullable
                                         java.lang.String description)

Sets the session description. Passing null will clear the description.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

description - the new description or null.

setSessionMark

public static void setSessionMark(@Nullable
                                  LogSession session,
                                  int mark)

Sets the session mark (star or flag). The default value is 0. Session marks supported by nRF Logger application: MARK_CLEAR, MARK_STAR_YELLOW, MARK_STAR_BLUE, MARK_STAR_RED, MARK_FLAG_YELLOW, MARK_FLAG_BLUE, MARK_FLAG_RED.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

mark - the new mark. MARK_CLEAR will clear the mark.

d

public static void d(@Nullable
                     ILogSession session,
                     @NonNull
                     java.lang.String message)

Logs the message in DEBUG (lowest) level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

message - the message to be logged.

v

public static void v(@Nullable
                     ILogSession session,
                     @NonNull
                     java.lang.String message)

Logs the message in VERBOSE level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

message - the message to be logged.

i

public static void i(@Nullable
                     ILogSession session,
                     @NonNull
                     java.lang.String message)

Logs the message in INFO level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

message - the message to be logged.

a

public static void a(@Nullable
                     ILogSession session,
                     @NonNull
                     java.lang.String message)

Logs the message in APPLICATION level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

message - the message to be logged.

w

public static void w(@Nullable
                     ILogSession session,
                     @NonNull
                     java.lang.String message)

Logs the message in WARNING level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

message - the message to be logged.

e

public static void e(@Nullable
                     ILogSession session,
                     @NonNull
                     java.lang.String message)

Logs the message in ERROR (highest) level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

message - the message to be logged.

log

public static void log(@Nullable
                       ILogSession session,
                       int level,
                       @NonNull
                       java.lang.String message)

Adds the log entry to nRF Logger log. If the parameter session is null it will exit immediately.

Parameters:

session - the session created using newSession(Context, String, String)

level - the log level, one of LogContract.Log.Level.DEBUG, LogContract.Log.Level.VERBOSE, LogContract.Log.Level.INFO, LogContract.Log.Level.APPLICATION, LogContract.Log.Level.WARNING, LogContract.Log.Level.ERROR.

message - the message to be logged.

logEntry

public static android.content.ContentValues logEntry(@Nullable
                                                     ILogSession session,
                                                     int level,
                                                     @NonNull
                                                     java.lang.String message)

Returns the log entry. If the parameter session is null it will exit immediately.

Parameters:

session - the session created using newSession(Context, String, String)

level - the log level, one of LogContract.Log.Level.DEBUG, LogContract.Log.Level.VERBOSE, LogContract.Log.Level.INFO, LogContract.Log.Level.APPLICATION, LogContract.Log.Level.WARNING, LogContract.Log.Level.ERROR.

message - the message to be logged.

d

public static void d(@Nullable
                     ILogSession session,
                     @StringRes
                     int messageResId,
                     java.lang.Object... params)

Logs the message in DEBUG (lowest) level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

messageResId - the log message resource id.

params - additional (optional) parameters used to fill the message.

v

public static void v(@Nullable
                     ILogSession session,
                     @StringRes
                     int messageResId,
                     java.lang.Object... params)

Logs the message in VERBOSE level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

messageResId - the log message resource id.

params - additional (optional) parameters used to fill the message.

i

public static void i(@Nullable
                     ILogSession session,
                     @StringRes
                     int messageResId,
                     java.lang.Object... params)

Logs the message in INFO level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

messageResId - the log message resource id.

params - additional (optional) parameters used to fill the message.

a

public static void a(@Nullable
                     ILogSession session,
                     @StringRes
                     int messageResId,
                     java.lang.Object... params)

Logs the message in APPLICATION level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

messageResId - the log message resource id.

params - additional (optional) parameters used to fill the message.

w

public static void w(@Nullable
                     ILogSession session,
                     @StringRes
                     int messageResId,
                     java.lang.Object... params)

Logs the message in WARNING level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

messageResId - the log message resource id.

params - additional (optional) parameters used to fill the message.

e

public static void e(@Nullable
                     ILogSession session,
                     @StringRes
                     int messageResId,
                     java.lang.Object... params)

Logs the message in ERROR (highest) level.

Parameters:

session - the session created using newSession(Context, String, String) method. This may be null, than it does nothing.

messageResId - the log message resource id.

params - additional (optional) parameters used to fill the message.

log

public static void log(@Nullable
                       ILogSession session,
                       int level,
                       @StringRes
                       int messageResId,
                       java.lang.Object... params)

Adds the log entry to nRF Logger log. If the parameter session is null it will exit immediately.

Parameters:

session - the session created using newSession(Context, String, String)

level - the log level, one of LogContract.Log.Level.DEBUG, LogContract.Log.Level.VERBOSE, LogContract.Log.Level.INFO, LogContract.Log.Level.APPLICATION, LogContract.Log.Level.WARNING, LogContract.Log.Level.ERROR.

messageResId - the log message resource id.

params - additional (optional) parameters used to fill the message.

logEntry

public static android.content.ContentValues logEntry(@Nullable
                                                     ILogSession session,
                                                     int level,
                                                     @StringRes
                                                     int messageResId,
                                                     java.lang.Object... params)

Returns the log entry. If the parameter session is null it will exit immediately.

Parameters:

session - the session created using newSession(Context, String, String)

level - the log level, one of LogContract.Log.Level.DEBUG, LogContract.Log.Level.VERBOSE, LogContract.Log.Level.INFO, LogContract.Log.Level.APPLICATION, LogContract.Log.Level.WARNING, LogContract.Log.Level.ERROR.

messageResId - the log message resource id.

params - additional (optional) parameters used to fill the message.

log

public static void log(@Nullable
                       ILogSession session,
                       @Nullable
                       android.content.ContentValues[] values)

Inserts an array of log entries in a bulk insert operation. The entry timestamp will be overwritten by the bulk operation time if used with nRF Logger 1.5 or older.

Parameters:

session - the session created using newSession(Context, String, String).

values - an array of values obtained using logEntry(ILogSession, int, String) method.

log

public static void log(@Nullable
                       ILogSession session,
                       @Nullable
                       java.util.List<android.content.ContentValues> values)

Inserts a list of log entries in a bulk insert operation. The entry timestamp will be overwritten by the bulk operation time if used with nRF Logger 1.5 or older.

Parameters:

session - the session created using newSession(Context, String, String).

values - a list of values obtained using logEntry(ILogSession, int, String) method.