activity

README

Activity Journals

The activity package maintains a collection of journals organized by journal ID. Each journal is stored in a separate file in the user's cache directory under wash/activity/<id>.log.

The journal ID should correspond to a universal unique identifier associated with whatever triggered any activity. This is usually a process ID and start time for that process.

Journals are kept open for several seconds after use then closed; they can be re-opened as necessary.

Documentation

Overview

Package activity provides tools for recording wash operations to journals stored in the user's cache directory. The cache directory is created at 'wash/activity' in the directory found via https://golang.org/pkg/os/#UserCacheDir. Journals are separated by Journal ID.

Wash plugins should use

activity.Record(ctx context.Context, msg string, a ...interface{})

to record entries, and

activity.Warnf(ctx context.Context, msg string, a ...interface{})

to warn about errors. The context contains the Journal ID.

Index

• func CloseAll()
• func Dir() string
• func Record(ctx context.Context, msg string, a ...interface{})
• func SetDir(dir string)
• func SubmitMethodInvocation(ctx context.Context, plugin string, entryType string, method string)
• func Warnf(ctx context.Context, msg string, a ...interface{})
• type Journal
  • func GetJournal(ctx context.Context) Journal
  • func History() []Journal
  • func JournalForPID(pid int) Journal
  • func NewJournal(id, desc string) Journal
  • func (j Journal) Open() (io.ReadCloser, error)
  • func (j Journal) Record(msg string, a ...interface{})
  • func (j Journal) Start() time.Time
  • func (j Journal) String() string
  • func (j Journal) Tail() (*tail.Tail, error)
  • func (j Journal) Warnf(msg string, a ...interface{})
• type KeyType
• type Writer
  • func (a Writer) Write(p []byte) (int, error)

Functions

func CloseAll

func CloseAll()

CloseAll ensures open journals are flushed to disk and closed. Use when the application is shutting down.

func Dir

func Dir() string

Dir gets the directory where journals are stored.

func Record

func Record(ctx context.Context, msg string, a ...interface{})

Record writes a new entry to the journal identified by the ID at `activity.JournalKey` in the provided context. It also writes to the server logs at the debug level. If no ID is registered, the entry is written to the server logs at the info level. If the ID is an empty string - which can happen when the JournalID header is missing from an API call - it uses the ID 'dead-letter-office'.

func SetDir

func SetDir(dir string)

SetDir sets the directory where journals are stored.

func SubmitMethodInvocation

func SubmitMethodInvocation(ctx context.Context, plugin string, entryType string, method string)

SubmitMethodInvocation submits a method invocation event to Google Analytics. It then records the invocation to the journal identified by the ID at `activity.JournalKey` in the provided context.

Note that entryType will typically be the type ID.

func Warnf

func Warnf(ctx context.Context, msg string, a ...interface{})

Warnf writes a new entry to the journal identified by the ID at `activity.JournalKey` in the provided context at WARN level. It also writes to the server logs at the same level. Use Warnf in plugin `Init` methods for issues during setup that will result in degraded behavior.

Types

type Journal

type Journal struct {
	ID, Description string
	// contains filtered or unexported fields
}

Journal is used to describe a log of activity. That activity is associated with a user-generated event by the ID, and can include a description and start time to provide further context when listed in activity history.

func GetJournal

func GetJournal(ctx context.Context) Journal

GetJournal returns the Journal stored in the context.

func History

func History() []Journal

History returns the entire history.

func JournalForPID

func JournalForPID(pid int) Journal

JournalForPID creates a journal that can be used to record all wash-related activity induced by the given process ID. Journal ID is formatted as `<pid>-<name>-<createtime>`.

func NewJournal

func NewJournal(id, desc string) Journal

NewJournal creates a new journal entry with start time set to 'now'.

func (Journal) Open

func (j Journal) Open() (io.ReadCloser, error)

Open returns a reader to read the journal.

func (Journal) Record

func (j Journal) Record(msg string, a ...interface{})

Record writes a new entry to the journal. It creates a new file for the journal if needed, then appends the message to that journal. Journals are stored in the user's cache directory under `wash/activity/ID.log`.

func (Journal) Start

func (j Journal) Start() time.Time

Start returns when the activity related to this journal started.

func (Journal) String

func (j Journal) String() string

func (Journal) Tail

func (j Journal) Tail() (*tail.Tail, error)

Tail streams updates to the journal.

func (Journal) Warnf

func (j Journal) Warnf(msg string, a ...interface{})

Warnf writes a new entry to the journal at WARN level. It also logs to the shell at the same level. It creates a new file for the journal if needed, then appends the message to that journal. Journals are stored in the user's cache directory under `wash/activity/ID.log`.

type KeyType

type KeyType int

KeyType is used to type keys for looking up context values.

const JournalKey KeyType = iota

JournalKey is used to identify a Journal in a context.

type Writer

type Writer struct {
	context.Context
	Prefix string
}

Writer logs the output as a call to Record per Write.

func (Writer) Write

func (a Writer) Write(p []byte) (int, error)