sls

README

sls

sls stands for Simple Logging Service. It's a server with an API that aggregates and broadcasts logs to other services.

API

POST /log
Header:
	Body-Content: application/json

Body:
	[
		"any content at all",
		"separated into elements",
		"in a json array",
	]

sls takes logs from the request body and broadcasts them to various targets. Targets are anything that implement the LogTarget interface:

type LogTarget interface {
	Name() string
	io.WriteCloser
}

Two LogTarget implementations are provided out-of-the-box:

• disk appends logs to a file on disk, automatically rotating the file every 24 hours and retaining files for a limited time. It's important to have enough HDD space for those log files. Writes to disk are threadsafe. Log files will be written to a given directory with the format YYYYMMDD.log.
• stackdriver sends logs asynchronously on a best-effort basis to Google's Stackdriver logging service.

Ordering: it's assumed that logs batched together in a single API call are from the same request or are related to the same action. Multiple requests (e.g. logs from several different HTTP requests) can be included in a single API call, but to ensure proper ordering, do not split up a request across API calls. A simple buffer that flushes to the API is not sufficient if ordering needs to be preserved.

Timestamps: sls does not add timestamps to logs. If needed, servers doing the logging should include them.

Auth: sls assumes that connections are initiated by trusted parties over a LAN.

!!! DO NOT EXPOSE SLS ON A PUBLIC PORT !!!

Configuration

Create config.json (or use the -c flag to specify a custom file), and fill it out with the following:

{
	"port": 9000,
	"targets": {
		"disk": {
			"dir": "/var/log",
			"retain_days": 30
		},
		"stackdriver": {
			"project_id": "your-project",
			"credential_file": "/path/to/service-file/google.json"
		}
	}
}

If you want to use only a particular target, omit the others from the config file.

Documentation

Index

• func Pledge(promises, execPromises string)
• func Unveil(filepath, perm string)
• func UnveilBlock()
• type Client
  • func NewClient(url string) *Client
  • func (c *Client) Err() <-chan error
  • func (c *Client) Log(s string)
  • func (c *Client) WithFlushInterval(dur time.Duration) (*Client, func())
  • func (c *Client) WithHTTPClient(client HTTPClient) *Client
  • func (c *Client) Write(byt []byte) (int, error)
• type HTTPClient
• type LogTarget
• type Logger

Functions

func Pledge

func Pledge(promises, execPromises string)

Pledge is only supported on OpenBSD.

func Unveil

func Unveil(filepath, perm string)

Unveil is only supported on OpenBSD.

func UnveilBlock

func UnveilBlock()

UnveilBlock is only supported on OpenBSD.

Types

type Client

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

Client is used to interact with the logging server.

func NewClient

func NewClient(url string) *Client

NewClient for interacting with sls.

func (*Client) Err

func (c *Client) Err() <-chan error

Err is a convenience function that wraps an error channel.

func (*Client) Log

func (c *Client) Log(s string)

Log to sls. This is threadsafe.

func (*Client) WithFlushInterval

func (c *Client) WithFlushInterval(dur time.Duration) (*Client, func())

WithFlushInterval specifies how long to wait before flushing the buffer to the log server. This returns a function which flushes the client and should be called with defer before main exits.

func (*Client) WithHTTPClient

func (c *Client) WithHTTPClient(client HTTPClient) *Client

func (*Client) Write

func (c *Client) Write(byt []byte) (int, error)

Write satisfies the io.Writer interface, so a client can be a drop-in replacement for stdout. Logs are written to the external service on a best-effort basis.

type HTTPClient

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPClient is satisfied by *http.Client but enables us to pass in alternative http clients as well with different features (such as automatic retries or allowing host-based communication over a LAN).

type LogTarget

type LogTarget interface {
	Name() string
	io.WriteCloser
}

LogTarget is something that SLS will write logs to.

type Logger

type Logger interface {
	Printf(string, ...interface{})
}

Logger is used to log internal sls events and has no bearing on the logs being aggregated or tailed out.