logevent - A structured event logger abstraction

• logevent - A structured event logger abstraction
  • Usage
    • Defining Events
    • Logging Events
    • Transaction IDs
    • Adding Adapters
  • Contributing
    • License
    • Contributing Agreement

Usage

Defining Events

There are no log events defined within this project. Instead, developers are free to create and maintain their own events structures and schema as preferred. This project relies on the tag annotation feature, like JSON, to render an event to the log stream.

Each event emitted must be defined as a struct. Each attribute of the struct must be annotated with a logevent tag that identifies the desired field name as it appears in the logs. Each struct must contain a Message attribute. Optionally, fields may include a default tag to auto-populate field values. For example, an event describing an a rate-limited call might appear as:

type UserOverLimit struct {
  UserID string `logevent:"user_id"`
  TenantID string `logevent:"tenant_id"`
  Message string `logevent:"message,default=user-over-limit"`
  AttemptsOverLimit int `logevent:"attempts_over_limit"`
}

Logging Events

logevent.FromContext(ctx).Info(myEvent{}) // Log the event
logevent.FromContext(ctx).SetField("key", "value")
logevent.FromContext(ctx).Warn("uh oh") // Fall back to string logging if not an event.
var newCtx = logevent.NewContext(context.Background(), logger.Copy())

Transaction IDs

You can add a transaction_id field to your logs by following the example below. Once a transaction id is set, all future logs written will automatically contain the transaction id. This is incredibly usefulfor tracing requests through a microservice and/or across multiple microservices. Note: if the transactionID parameter is left empty, a uuid will be randomly generated for you.

logger := logevent.New(logevent.Config{Level: "INFO"})
ctx := logevent.NewContext(context.Background(), logger)
logevent.SetTransactionID(ctx, &logger, "1234")

To retrieve a previously set transaction id, follow this example:

txid := logevent.GetTransactionID(ctx)

Adding Adapters

Contributing

License

This project is licensed under Apache 2.0. See LICENSE.txt for details.

Contributing Agreement

Atlassian requires signing a contributor's agreement before we can accept a patch. If you are an individual you can fill out the individual CLA. If you are contributing on behalf of your company then please fill out the corporate CLA.