logstream

README

How to use logstream

This is a guide to start using logstream in your e2e testing.

Requirements

1. The SYSTEM_NAMESPACE environment variable must be configured. Many of the knative test scripts already define this, and in some places (e.g. serving) randomize it. However, to facilitate usage outside of CI, you should consider including a package like this and linking it like this

2. Test resources must be named with test.ObjectNameForTest(t)

3. At the start of your test add: t.Cleanup(logstream.Start(t))

4. To enable logcapture from containers across multiple namespaces configure SYSTEM_NAMESPACE to contains a csv list of namespaces (knative-serving,knative-test ??????{}). Specific, well known containers that do not produce key decorated logs (see detailed description below) need to be enumerated in WellKnownContainers in stream.go.

With that, you will start getting logs from the processes in the system namespace interleaved into your test output via t.Log.

How it works

In Knative we use zap.Logger for all of our logging, and most of those loggers (e.g. in the context of a reconcile) have been decorated with the "key" of the resource being processed. logstream simply decodes these structured log messages and when the key matches the naming prefix that ObjectNameForTest uses, it includes it into the test's output.

Integrating in Libraries.

When a shared component is set up and called from reconciliation, it may have it's own logger. If that component is dealing with individual resources, it can scope individual log statements to that resource by decorating the logger with its key like so:

logger := logger.With(zap.String(logkey.Key, resourceKey))

Now, any log statements that the library prints through this logger will appear in the logstream!

For an example of this pattern, see the knative/networking prober library.

Documentation

Overview

Package logstream lets end-to-end tests incorporate controller logs into the error output of tests. It is enabled by setting the SYSTEM_NAMESPACE environment variable, which tells this package what namespace to stream logs from.

Index

• type Canceler
  • func Start(t ti) Canceler

Types

type Canceler

type Canceler = logstreamv2.Canceler

Canceler is the type of a function returned when a logstream is started to be deferred so that the logstream can be stopped when the test is complete.

func Start

func Start(t ti) Canceler

Start begins streaming the logs from system components with a `key:` matching `test.ObjectNameForTest(t)` to `t.Log`. It returns a Canceler, which must be called before the test completes.