traefiklogger

README

First of all

Usage example

Developing a Traefik plugin

Traefik plugins are developed using the Go language.

A Traefik middleware plugin is just a Go package that provides an http.Handler to perform specific processing of requests and responses.

Rather than being pre-compiled and linked, however, plugins are executed on the fly by Yaegi, an embedded Go interpreter.

Usage

For a plugin to be active for a given Traefik instance, it must be declared in the static configuration.

Plugins are parsed and loaded exclusively during startup, which allows Traefik to check the integrity of the code and catch errors early on. If an error occurs during loading, the plugin is disabled.

For security reasons, it is not possible to start a new plugin or modify an existing one while Traefik is running.

Once loaded, middleware plugins behave exactly like statically compiled middlewares. Their instantiation and behavior are driven by the dynamic configuration.

Plugin dependencies must be vendored for each plugin. Vendored packages should be included in the plugin's GitHub repository. (Go modules are not supported.)

Configuration

For each plugin, the Traefik static configuration must define the module name (as is usual for Go packages).

The following declaration (given here in YAML) defines a plugin:

# Static configuration

experimental:
  plugins:
    example:
      moduleName: github.com/fzoli/traefiklogger
      version: v0.1.0

Here is an example of a file provider dynamic configuration (given here in YAML), where the interesting part is the http.middlewares section:

# Dynamic configuration

http:
  routers:
    my-router:
      rule: host(`demo.localhost`)
      service: service-foo
      entryPoints:
        - web
      middlewares:
        - my-plugin

  services:
   service-foo:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:5000
  
  middlewares:
    my-plugin:
      plugin:
        example:
          headers:
            Foo: Bar

Local Mode

Traefik also offers a developer mode that can be used for temporary testing of plugins not hosted on GitHub. To use a plugin in local mode, the Traefik static configuration must define the module name (as is usual for Go packages) and a path to a Go workspace, which can be the local GOPATH or any directory.

The plugins must be placed in ./plugins-local directory, which should be in the working directory of the process running the Traefik binary. The source code of the plugin should be organized as follows:

./plugins-local/
    └── src
        └── github.com
            └── fzoli
                └── traefiklogger
                    ├── plugin.go
                    ├── plugin_test.go
                    ├── go.mod
                    ├── LICENSE
                    ├── Makefile
                    └── readme.md

# Static configuration

experimental:
  localPlugins:
    example:
      moduleName: github.com/fzoli/traefiklogger

(In the above example, the traefiklogger plugin will be loaded from the path ./plugins-local/src/github.com/fzoli/traefiklogger.)

# Dynamic configuration

http:
  routers:
    my-router:
      rule: host(`demo.localhost`)
      service: service-foo
      entryPoints:
        - web
      middlewares:
        - my-plugin

  services:
   service-foo:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:5000
  
  middlewares:
    my-plugin:
      plugin:
        example:
          headers:
            Foo: Bar

Defining a Plugin

A plugin package must define the following exported Go objects:

• A type type Config struct { ... }. The struct fields are arbitrary.
• A function func CreateConfig() *Config.
• A function func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error).

// Package example a example plugin.
package example

import (
	"context"
	"net/http"
)

// Config the plugin configuration.
type Config struct {
	// ...
}

// CreateConfig creates the default plugin configuration.
func CreateConfig() *Config {
	return &Config{
		// ...
	}
}

// Example a plugin.
type Example struct {
	next     http.Handler
	name     string
	// ...
}

// New created a new plugin.
func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error) {
	// ...
	return &Example{
		// ...
	}, nil
}

func (e *Example) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
	// ...
	e.next.ServeHTTP(rw, req)
}

Logs

Currently, the only way to send logs to Traefik is to use os.Stdout.WriteString("...") or os.Stderr.WriteString("...").

In the future, we will try to provide something better and based on levels.

Plugins Catalog

Traefik plugins are stored and hosted as public GitHub repositories.

Every 30 minutes, the Plugins Catalog online service polls Github to find plugins and add them to its catalog.

Prerequisites

To be recognized by Plugins Catalog, your repository must meet the following criteria:

• The traefik-plugin topic must be set.
• The .traefik.yml manifest must exist, and be filled with valid contents.

If your repository fails to meet either of these prerequisites, Plugins Catalog will not see it.

Manifest

A manifest is also mandatory, and it should be named .traefik.yml and stored at the root of your project.

This YAML file provides Plugins Catalog with information about your plugin, such as a description, a full name, and so on.

Here is an example of a typical .traefik.ymlfile:

# The name of your plugin as displayed in the Plugins Catalog web UI.
displayName: Name of your plugin

# For now, `middleware` is the only type available.
type: middleware

# The import path of your plugin.
import: github.com/username/my-plugin

# A brief description of what your plugin is doing.
summary: Description of what my plugin is doing

# Medias associated to the plugin (optional)
iconPath: foo/icon.png
bannerPath: foo/banner.png

# Configuration data for your plugin.
# This is mandatory,
# and Plugins Catalog will try to execute the plugin with the data you provide as part of its startup validity tests.
testData:
  Headers:
    Foo: Bar

Properties include:

• displayName (required): The name of your plugin as displayed in the Plugins Catalog web UI.
• type (required): For now, middleware is the only type available.
• import (required): The import path of your plugin.
• summary (required): A brief description of what your plugin is doing.
• testData (required): Configuration data for your plugin. This is mandatory, and Plugins Catalog will try to execute the plugin with the data you provide as part of its startup validity tests.
• iconPath (optional): A local path in the repository to the icon of the project.
• bannerPath (optional): A local path in the repository to the image that will be used when you will share your plugin page in social medias.

There should also be a go.mod file at the root of your project. Plugins Catalog will use this file to validate the name of the project.

Tags and Dependencies

Plugins Catalog gets your sources from a Go module proxy, so your plugins need to be versioned with a git tag.

Last but not least, if your plugin middleware has Go package dependencies, you need to vendor them and add them to your GitHub repository.

If something goes wrong with the integration of your plugin, Plugins Catalog will create an issue inside your Github repository and will stop trying to add your repo until you close the issue.

Troubleshooting

If Plugins Catalog fails to recognize your plugin, you will need to make one or more changes to your GitHub repository.

In order for your plugin to be successfully imported by Plugins Catalog, consult this checklist:

• The traefik-plugin topic must be set on your repository.
• There must be a .traefik.yml file at the root of your project describing your plugin, and it must have a valid testData property for testing purposes.
• There must be a valid go.mod file at the root of your project.
• Your plugin must be versioned with a git tag.
• If you have package dependencies, they must be vendored and added to your GitHub repository.

Documentation

Overview

Package traefiklogger a Traefik HTTP logger plugin.

Package traefiklogger a Traefik HTTP logger plugin.

Package traefiklogger a Traefik HTTP logger plugin.

Package traefiklogger a Traefik HTTP logger plugin.

Index

• Constants
• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• type CompressHTTPDecoder
• type Config
  • func CreateConfig() *Config
• type DeflateHTTPDecoder
• type EmptyUUIDGenerator
  • func (g *EmptyUUIDGenerator) Generate() string
• type FileLogWriter
  • func (w *FileLogWriter) Write(log string) error
• type GZipHTTPDecoder
• type HTTPBodyDecoder
• type HTTPBodyDecoderFactory
• type HTTPLogger
• type JSONHTTPLogger
• type LogFormat
• type LogRecord
• type LogWriter
• type LoggerClock
• type LoggerLogWriter
  • func (w *LoggerLogWriter) Write(log string) error
• type LoggerMiddleware
  • func (m *LoggerMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type NoOpMiddleware
  • func (m *NoOpMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type RandomUUIDGenerator
  • func (g *RandomUUIDGenerator) Generate() string
• type RawHTTPDecoder
• type SystemLoggerClock
  • func (*SystemLoggerClock) Now() time.Time
• type TextualHTTPLogger
• type UUID
  • func GenerateUUID4() (UUID, error)
  • func Must(u UUID, err error) UUID
  • func (u UUID) String() string
• type UUIDGenerator

Constants

const ClockContextKey clockContextKey = "clock"

ClockContextKey can be used to fake time.

const LogWriterContextKey logWriterContextKey = "log-writer"

LogWriterContextKey can be used to spy log writes.

const UUIDGeneratorContextKey uuidGeneratorContextKey = "uuid-generator"

UUIDGeneratorContextKey can be used to fake UUID generator.

Functions

func New

func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

New creates a new LoggerMiddleware plugin.

Types

type CompressHTTPDecoder

type CompressHTTPDecoder struct {
	// contains filtered or unexported fields
}

CompressHTTPDecoder extracts with the Lempel-Ziv-Welch (LZW) algorithm.

type Config

type Config struct {
	Enabled            bool      `json:"enabled"`
	Debug              bool      `json:"debug"`
	LogFormat          LogFormat `json:"logFormat"`
	GenerateLogID      bool      `json:"generateLogId,omitempty"`
	Name               string    `json:"name,omitempty"`
	BodyContentTypes   []string  `json:"bodyContentTypes,omitempty"`
	JWTHeaders         []string  `json:"jwtHeaders,omitempty"`
	HeaderRedacts      []string  `json:"headerRedacts,omitempty"`
	RequestBodyRedact  string    `json:"requestBodyRedact,omitempty"`
	ResponseBodyRedact string    `json:"responseBodyRedact,omitempty"`
}

Config the plugin configuration.

func CreateConfig

func CreateConfig() *Config

CreateConfig creates the default plugin configuration.

type DeflateHTTPDecoder

type DeflateHTTPDecoder struct {
	// contains filtered or unexported fields
}

DeflateHTTPDecoder extracts the zlib structure with the deflate compression algorithm.

type EmptyUUIDGenerator

type EmptyUUIDGenerator struct{}

EmptyUUIDGenerator returns empty string.

func (*EmptyUUIDGenerator) Generate

func (g *EmptyUUIDGenerator) Generate() string

Generate returns empty string.

type FileLogWriter

type FileLogWriter struct {
	// contains filtered or unexported fields
}

FileLogWriter writes logs to a File (like stdout).

func (*FileLogWriter) Write

func (w *FileLogWriter) Write(log string) error

type GZipHTTPDecoder

type GZipHTTPDecoder struct {
	// contains filtered or unexported fields
}

GZipHTTPDecoder extracts the Lempel-Ziv coding (LZ77) with a 32-bit CRC.

type HTTPBodyDecoder

type HTTPBodyDecoder interface {
	// contains filtered or unexported methods
}

HTTPBodyDecoder a body decoder strategy.

type HTTPBodyDecoderFactory

type HTTPBodyDecoderFactory struct {
	// contains filtered or unexported fields
}

HTTPBodyDecoderFactory selects which decoder should run.

type HTTPLogger

type HTTPLogger interface {
	// contains filtered or unexported methods
}

HTTPLogger a logger strategy interface.

type JSONHTTPLogger

type JSONHTTPLogger struct {
	// contains filtered or unexported fields
}

JSONHTTPLogger a JSON logger implementation.

type LogFormat

type LogFormat string

LogFormat specifies the log format.

const (
	// TextFormat indicates text log format.
	TextFormat LogFormat = "text"
	// JSONFormat indicates JSON log format.
	JSONFormat LogFormat = "json"
)

type LogRecord

type LogRecord struct {
	System                string
	Proto                 string
	Method                string
	URL                   string
	RemoteAddr            string
	StatusCode            int
	RequestHeaders        http.Header
	RequestBody           *bytes.Buffer
	ResponseHeaders       http.Header
	ResponseBody          *bytes.Buffer
	ResponseContentLength int
	DurationMs            float64
	BodyDecoder           HTTPBodyDecoder
}

LogRecord contains the loggable data.

type LogWriter

type LogWriter interface {
	Write(log string) error
}

LogWriter is a write strategy.

type LoggerClock

type LoggerClock interface {
	Now() time.Time
}

LoggerClock is the source of current time.

type LoggerLogWriter

type LoggerLogWriter struct {
	// contains filtered or unexported fields
}

LoggerLogWriter writes logs to a Logger.

func (*LoggerLogWriter) Write

func (w *LoggerLogWriter) Write(log string) error

type LoggerMiddleware

type LoggerMiddleware struct {
	// contains filtered or unexported fields
}

LoggerMiddleware a Logger plugin.

func (*LoggerMiddleware) ServeHTTP

func (m *LoggerMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request)

type NoOpMiddleware

type NoOpMiddleware struct {
	// contains filtered or unexported fields
}

NoOpMiddleware a no-op plugin implementation.

func (*NoOpMiddleware) ServeHTTP

func (m *NoOpMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request)

type RandomUUIDGenerator

type RandomUUIDGenerator struct{}

RandomUUIDGenerator generates secure random UUID v4.

func (*RandomUUIDGenerator) Generate

func (g *RandomUUIDGenerator) Generate() string

Generate generates secure random UUID.

type RawHTTPDecoder

type RawHTTPDecoder struct{}

RawHTTPDecoder just returns the content as-is.

type SystemLoggerClock

type SystemLoggerClock struct{}

SystemLoggerClock uses OS system time.

func (*SystemLoggerClock) Now

func (*SystemLoggerClock) Now() time.Time

Now returns current OS system time.

type TextualHTTPLogger

type TextualHTTPLogger struct {
	// contains filtered or unexported fields
}

TextualHTTPLogger a textual logger implementation.

type UUID

type UUID [16]byte

UUID representation compliant with specification described in RFC 4122.

func GenerateUUID4

func GenerateUUID4() (UUID, error)

GenerateUUID4 generates RFC 4122 version 4 UUID.

func Must

func Must(u UUID, err error) UUID

Must is a helper that wraps a call to a function returning (UUID, error) and panics if the error is non-nil.

func (UUID) String

func (u UUID) String() string

String returns canonical string representation of UUID.

type UUIDGenerator

type UUIDGenerator interface {
	Generate() string
}

UUIDGenerator is a UUID generator strategy.