logcat

Documentation

Overview

Package logcat implements a logcat-like functionality for ooniprobe.

The logcat dispatches log messages emitted by the OONI engine. We internally store log messages on a ring buffer that mobile apps will be able to access in order to get recent logs. To get recent logs, use the Read public function, which returns them.

We also allow streaming logs to apex/log-like loggers. To this end, you need to call StartConsumer. The consumer is a background goroutine that extracts and dispatches logger to an apex/log-like logger. You provide StartConsumer with a context. When the context is done, we'll automatically de-register the consumer. The logcat will buffer messages to consumers in case they're not reading them fast enough. When the buffer is full, we'll discard new messages.

This package supports emitting log messages containing emojis, which you can configure on a per-consumer-specific basis.

Index

• Constants
• func Bug(message string)
• func Bugf(format string, value ...interface{})
• func Cache(message string)
• func Cachef(format string, value ...interface{})
• func Celebrate(message string)
• func Celebratef(format string, value ...interface{})
• func Confirmed(message string)
• func Confirmedf(format string, value ...interface{})
• func Debug(message string)
• func Debugf(format string, values ...interface{})
• func DefaultLogger(w io.Writer, flags int64) model.Logger
• func Emit(level, emoji int64, message string)
• func Emitf(level, emoji int64, format string, values ...interface{})
• func IncrementLogLevel(increment int)
• func Info(message string)
• func Infof(format string, values ...interface{})
• func Inspect(message string)
• func Inspectf(format string, value ...interface{})
• func NewInput(message string)
• func NewInputf(format string, value ...interface{})
• func Notice(message string)
• func Noticef(format string, values ...interface{})
• func Scrutinize(message string)
• func Scrutinizef(format string, value ...interface{})
• func Shrug(message string)
• func Shrugf(format string, value ...interface{})
• func StartConsumer(ctx context.Context, logger model.Logger, emojis bool, wg *sync.WaitGroup)
• func Step(message string)
• func Stepf(format string, value ...interface{})
• func Substep(message string)
• func Substepf(format string, value ...interface{})
• func Trace(message string)
• func Tracef(format string, values ...interface{})
• func Unexpected(message string)
• func Unexpectedf(format string, value ...interface{})
• func Warn(message string)
• func Warnf(format string, values ...interface{})
• type Msg
  • func Read() []Msg

Constants

const (
	// WARNING is only emitted when a specific operation fails and
	// this fact may have implications on subsequent operations.
	WARNING = iota

	// NOTICE is the standard logging level where we only emit
	// a minimal amount to message to convey progress.
	NOTICE

	// INFO contains informational messages explaining to the user
	// what the program is doing and why.
	INFO

	// DEBUG increases the software verbosity compared to INFO
	// but not at the level of detail provided by TRACE.
	DEBUG

	// TRACE provides the most detailed level of logging where we
	// show individual operations that we perform.
	TRACE
)

These values control the log level.

const (
	// BUG indicates that this log message refers to a bug.
	BUG = iota + 1

	// CACHE indicates a message from the cache.
	CACHE

	// STEP is the beginning of a measurement step.
	STEP

	// SUBSTEP is the beginning of a measurement substep.
	SUBSTEP

	// NEW_INPUT is a message indicating we're starting a new run of
	// an experiment with the provided input.
	NEW_INPUT

	// SHRUG is a message about an unexpected situation that is out of our
	// control (as opposed to BUG, which is under our control.)
	SHRUG

	// SCRUTINIZE is a message indicating that we're questioning or inspecting
	// something or taking optimizing decisions.
	SCRUTINIZE

	// CELEBRATE is a message emitted when we're happy about something
	// we discovered or about a result that looks accessible.
	CELEBRATE

	// UNEXPECTED is a message emitted when we see something surprising
	// for example an unexpected timeout or other soft anomalies.
	UNEXPECTED

	// CONFIRMED is a message emitted when we see something really
	// interesting and wrong, e.g., a bogon IP address.
	CONFIRMED

	// INSPECT is emitted when you start inspecting something. The difference
	// with scrutinize is that INSPECT is just informationl and does not
	// imply taking any kind of weighted decision.
	INSPECT
)

These values control which emoji to display.

const DefaultLoggerWriteTimestamps = 1 << iota

DefaultLoggerWriteTimestamps tells the default logger that we would like absolute timestamps in the log.

Functions

func Bug

func Bug(message string)

Bug is a convenience function for emitting a log message about a bug. By default this log message will be at WARNING level. We may be continuing to run after we notice there's a bug, but subsequent results may be influenced by that.

func Bugf

func Bugf(format string, value ...interface{})

Bugf is like Bug but allows formatting a message.

func Cache

func Cache(message string)

Cache is a convenience function for emitting messages related to the cache. The user should not see these messages by default unless they want more details. For this reason we emit this kind of messages at the INFO level.

func Cachef

func Cachef(format string, value ...interface{})

Cachef is like Cache but allows formatting a message.

func Celebrate

func Celebrate(message string)

Celebrate is the function to call when you discover something interesting and positive (e.g., that a website is accessible).

func Celebratef

func Celebratef(format string, value ...interface{})

Celebratef is like Celebrate but with log message formatting.

func Confirmed

func Confirmed(message string)

Confirmed is the function to call with serious anomalies (e.g. bogon).

func Confirmedf

func Confirmedf(format string, value ...interface{})

Confirmedf is like Confirmed but with message formatting.

func Debug

func Debug(message string)

Debug emits a DEBUG message.

func Debugf

func Debugf(format string, values ...interface{})

Debugf formats and emits a DEBUG message.

func DefaultLogger

func DefaultLogger(w io.Writer, flags int64) model.Logger

DefaultLogger returns the default model.Logger. This logger will just print the provided messages to the given io.Writer.

func Emit

func Emit(level, emoji int64, message string)

Emit emits a log message to the logcat using the given level.

func Emitf

func Emitf(level, emoji int64, format string, values ...interface{})

Emitf is a variation of Emit that allows you to format a message.

func IncrementLogLevel

func IncrementLogLevel(increment int)

IncrementLogLevel increments the log level the specified number of times. Use a negative increment value to decrement the log level.

func Info

func Info(message string)

Info emits an INFO message.

func Infof

func Infof(format string, values ...interface{})

Infof formats and emits an INFO message.

func Inspect

func Inspect(message string)

Inspect informs the user we're starting to look into something.

func Inspectf

func Inspectf(format string, value ...interface{})

Inspectf is like Inspect but with formatting.

func NewInput

func NewInput(message string)

NewInput is the function to call when you are an experiment and you receive new input. This is also part of the NOTICEs.

func NewInputf

func NewInputf(format string, value ...interface{})

NewInputf is like NewInput but allows formatting messages.

func Notice

func Notice(message string)

Notice emits a NOTICE message.

func Noticef

func Noticef(format string, values ...interface{})

Noticef formats and emits a NOTICE message.

func Scrutinize

func Scrutinize(message string)

Scrutinize is the function to call when we're looking deeply into something or questioning the truth of something or choosing not to perform measurements due to optimizations.

func Scrutinizef

func Scrutinizef(format string, value ...interface{})

Scrutinizef is like Inspect but allows formatting a log message.

func Shrug

func Shrug(message string)

Shrug is a convenience function for emitting log messages detailing that something not under our control went wrong and we don't know what to do about this. We emit these messaeges as warnings because we users to let us know about these errors.

func Shrugf

func Shrugf(format string, value ...interface{})

Shrugf is like Shrug but allows formatting a message,

func StartConsumer

func StartConsumer(ctx context.Context, logger model.Logger, emojis bool, wg *sync.WaitGroup)

StartConsumer starts a consumer that consumes log messages and dispatches them to the given logger. The consumer will gracefully exit when the provided context expires.

The wg argument is incremented before starting the background goroutine and decremented when we're done writing all the logs (which may be slow when using SSH). Hence, when wg has been decremented, you know we've written all the logs.

Of course, if you want to do this shutdown protocol that ensures we've written all the logs, you also need to cancel the context when the test is done, to notify the consumer that it should start to prepare to shutdown.

func Step

func Step(message string)

Step is a convenience function for emitting log messages related to one of several steps within an experiment. These are NOTICEs.

func Stepf

func Stepf(format string, value ...interface{})

Stepf is like Step but allows formatting messages.

func Substep

func Substep(message string)

Substep is a convenience function for emitting log messages related to one of several substeps within a step. These are NOTICEs.

func Substepf

func Substepf(format string, value ...interface{})

Substepf is like Substep but allows formatting messages.

func Trace

func Trace(message string)

Trace emits a TRACE message.

func Tracef

func Tracef(format string, values ...interface{})

Tracef formats and emits a TRACE message.

func Unexpected

func Unexpected(message string)

Unexpected is the function to call when you see some soft anomaly.

func Unexpectedf

func Unexpectedf(format string, value ...interface{})

Unexpectedf is like Unexpected but with message formatting.

func Warn

func Warn(message string)

Warn emits a WARNING message.

func Warnf

func Warnf(format string, values ...interface{})

Warnf formats and emits a WARNING message.

Types

type Msg

type Msg struct {
	// Level is the message Level.
	Level int64

	// Emoji is the emoji.
	Emoji int64

	// Message is the actual Message.
	Message string

	// Time is the Time when we collected the message.
	Time time.Time
}

Msg contains a log message.

func Read

func Read() []Msg

Read reads all the buffered log messages.