formatencoder

README

Formatted Encoder Module for Caddy's Logger

This plugin adds logging encoder named formatted. The module accepts a template with the placeholders are surrounded by braces {} and filled by values extracted from the stucture of the JSON log encoder. The JSON configuration looks like this:

{
	"encoder": "formatted",
	"template": "{...}"
}

The nesting is traversed using >. For example, to print the uri field, the traversal is templated as {request>uri}.

{
	"request": {
		"method": "GET",
		"uri": "/",
		"proto": "HTTP/2.0",
		...
}

The Caddyfile configuration accepts the template immediately following the encoder name, and can be ommitted to assume Apache Common Log Format.

log {
	format formatted [<template>] {
		placeholder <string>
		message_key <key>
		level_key   <key>
		time_key    <key>
		name_key    <key>
		caller_key  <key>
		stacktrace_key <key>
		line_ending  <char>
		time_format  <format>
		level_format <format>
	}
}

The syntax of template is defined by the package github.com/buger/jsonparser. Objects are traversed using the key name. Arrays can be traversed by using the format [index], as in [0]. For example, to get the first element in the User-Agent array, the template is {request>headers>User-Agent>[0]}.

Install

First, the xcaddy command:

$ go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

Then build Caddy with this Go module plugged in. For example:

$ xcaddy build --with github.com/caddyserver/format-encoder

Documentation

Index

• type FormattedEncoder
  • func (FormattedEncoder) CaddyModule() caddy.ModuleInfo
  • func (se FormattedEncoder) Clone() zapcore.Encoder
  • func (se FormattedEncoder) EncodeEntry(ent zapcore.Entry, fields []zapcore.Field) (*buffer.Buffer, error)
  • func (se *FormattedEncoder) Provision(ctx caddy.Context) error
  • func (se *FormattedEncoder) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Types

type FormattedEncoder

type FormattedEncoder struct {
	logging.LogEncoderConfig
	zapcore.Encoder `json:"-"`
	Template        string `json:"template,omitempty"`
	Placeholder     string `json:"placeholder,omitempty"`
}

FormattedEncoder allows the user to provide custom template for log prints. The encoder builds atop the json encoder, thus it follows its message structure. The placeholders are namespaced by the name of the app logging the message.

func (FormattedEncoder) CaddyModule

func (FormattedEncoder) CaddyModule() caddy.ModuleInfo

func (FormattedEncoder) Clone

func (se FormattedEncoder) Clone() zapcore.Encoder

Clone wraps the underlying encoder's Clone. This is necessary because we implement our own EncodeEntry, and if we simply let the embedded encoder's Clone be promoted, it would return a clone of that, and we'd lose our FormattedEncoder's EncodeEntry.

func (FormattedEncoder) EncodeEntry

func (se FormattedEncoder) EncodeEntry(ent zapcore.Entry, fields []zapcore.Field) (*buffer.Buffer, error)

EncodeEntry partially implements the zapcore.Encoder interface.

func (*FormattedEncoder) Provision

func (se *FormattedEncoder) Provision(ctx caddy.Context) error

Provision sets up the encoder.

func (*FormattedEncoder) UnmarshalCaddyfile

func (se *FormattedEncoder) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens. Syntax:

formatted [<template>] [{
     placeholder	[<placeholder>]
}]

If the value of "template" is omitted, Common Log Format is assumed. See the godoc on the LogEncoderConfig type for the syntax of subdirectives that are common to most/all encoders.