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
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.
Variables ¶
This section is empty.
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 Debugf ¶
func Debugf(format string, values ...interface{})
Debugf formats and emits a DEBUG message.
func DefaultLogger ¶
DefaultLogger returns the default model.Logger. This logger will just print the provided messages to the given io.Writer.
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 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 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 ¶
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 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.
Source Files