kayvee

README

kayvee

import "gopkg.in/Clever/kayvee-go.v6"

Package kayvee provides methods to output human and machine parseable strings, with a "json" format.

Logger API Documentation

• gopkg.in/Clever/kayvee-go.v6/logger
• gopkg.in/Clever/kayvee-go.v6/middleware

Examples

// main.go
package main

import (
    l "log"
    "os"
    "path"
    "time"

    "gopkg.in/Clever/kayvee-go.v6/logger"
)

var log = logger.New("myApp")

func init() {
    exePath, err := os.Executable()
    if err != nil {
        l.Fatal(err)
    }
    dir := path.Dir(exePath)
    err = logger.SetGlobalRouting(path.Join(dir, "kvconfig.yml"))
    if err != nil {
        l.Fatal(err)
    }
}

func main() {
    // Simple debugging
    log.Debug("Service has started")

    // Make a query and log its length
    query_start := time.Now()
    log.GaugeFloat("QueryTime", time.Since(query_start).Seconds())

    // Output structured data
    log.InfoD("DataResults", logger.M{"key": "value"})  // Sends slack message (see Log Routing)

    // You can use the M alias for your key value pairs
    log.InfoD("DataResults", logger.M{"shorter": "line"}) // will NOT send slack message
}

Log Routing

Log routing is a mechanism for defining where log lines should go once they've entered Clever's logging pipeline. Routes are defined in a yaml file called kvconfig.yml. Here's an example of a log routing rule that sends a slack message:

# kvconfig.yml
routes:
  key-val: # Rule name
    matchers:
      title: [ "DataResults", "QueryResults" ]
      key: [ "value" ]
    output: # Routes log line to #data-dinesty slack channel
      type: "notifications"
      channel: "#data-dinesty"
      icon: ":bird:"
      message: "The data is in: %{key}"
      user: "The Data Duck"

For more information see https://clever.atlassian.net/wiki/display/ENG/Application+Log+Routing

Testing

Run make test to execute the tests

Testing Log Routing

A mock logger is provided to make it easier to test log routing rules. Here's an exampe:

// Units for main.go which is defined in the examples section of this README
package main

import (
    l "log"
    "testing"

    "github.com/stretchr/testify/assert"
    "gopkg.in/Clever/kayvee-go.v6/logger"
)

func init() {
    err := logger.SetGlobalRouting("./kvconfig.yml")
    if err != nil {
        l.Fatal(err)
    }
}

func TestDataResultsRouting(t *testing.T) {
    assert := assert.New(t)

    mocklog := logger.NewMockCountLogger("myApp")

    // Overrides package level logger
    log = mocklog

    main() // Call function to generate log lines

    counts := mocklog.RuleCounts()

    assert.Contains(counts, "key-val")
    assert.Equal(counts["key-val"], 1)
}

Testing Slack notifications in stage

Slack messages in the clever-dev environment are routed to a separate Slack team called clever-test. To see your dev notifications, create an account on https://clever-test.slack.com/ and create the slack channel your notifications should appear in.

Change log

• v6.0 - Introduced log-routing
• v5.0 - Middleware logger now creates a new logger on each request.
  • Breaking change to middleware.New constructor.
• v4.0
  • Added methods to read and write the Logger object from a a context.Context object.
  • Middleware now injects the logger into the request context.
  • Updated to require Go 1.7.
• v4.0 - Removed sentry-go dependency
• v2.4 - Add kayvee-go/validator for asserting that raw log lines are in a valid kayvee format.
• v2.3 - Expose logger.M.
• v2.2 - Remove godeps.
• v2.1 - Add kayvee-go/logger with log level, counters, and gauge support
• v0.1 - Initial release.

Backward Compatibility

The kayvee 1.x interface still exist but is considered deprecated. You can find documentation on using it in the compatibility guide

Publishing

To release a new version run make bump-major, make bump-minor, or make bump-patch as appropriate on master (after merging your PR). Then, run git push --tags.

Documentation

Overview

Package kayvee provides methods to output human and machine parseable strings, with a "key=val" format.

## Example

Here's an example program that outputs a kayvee formatted string:

package main

import(
  "fmt"
  "gopkg.in/Clever/kayvee.v0"
)

func main() {
  fmt.Println(kayvee.Format(map[string]interface{}{"hello": "world"}))
}

## Testing

Run `make test` to execute the tests

## Change log

v0.0.1 - Initial release.

Index

• Constants
• Variables
• func Format(data map[string]interface{}) string
• func FormatLog(source string, level LogLevel, title string, data map[string]interface{}) string
• type LogLevel
• type Logger

Constants

const (
	Unknown  LogLevel = "unknown"
	Critical          = "critical"
	Error             = "error"
	Warning           = "warning"
	Info              = "info"
	Trace             = "trace"
)

Constants used to define different LogLevels supported

Variables

var Version = "6.20.0"

Version is a string containing the version of this library.

Functions

func Format

func Format(data map[string]interface{}) string

Format converts a map to a string of space-delimited key=val pairs

func FormatLog

func FormatLog(source string, level LogLevel, title string, data map[string]interface{}) string

FormatLog is similar to Format, but takes additional reserved params to promote logging best-practices

Types

type LogLevel

type LogLevel string

LogLevel denotes the level of a logging

type Logger

type Logger interface {
	Info(title string, data map[string]interface{})
	Warning(title string, data map[string]interface{})
	Error(title string, data map[string]interface{}, err error)
}

Logger is an interface satisfied by all loggers that use kayvee to Log results