audit

README

Audit Events

Audit Events are pieces of data that describe a particular thing that has happened in a system. At Flipt, we provide the functionality of processing and batching these audit events and an abstraction for sending these audit events to a sink.

If you have an idea of a sink that you would like to receive audit events on, there are certain steps you would need to take to contribute, which are detailed below.

Filterable Audit Events

The ability to filter audit events was added in v1.27.0 of Flipt. The following audit events are currently filterable:

Nouns

• flag
• segment
• variant
• constraint
• rule
• distribution
• namespace
• rollout
• token

Verbs

• created
• updated
• deleted

Any combination of the above nouns and verbs can be used to filter audit events. For example, flag:created would filter audit events for only created events for flags.

You may also use the * wildcard to filter on all nouns or verbs. For example, *:created would filter audit events for only created events for all nouns.

Similarly, flag:* would filter audit events for all verbs for flags.

Finally, *:* would filter audit events for all nouns and verbs which is the default behavior.

Contributing

The abstraction that we provide for implementation of receiving these audit events to a sink is this.

type Sink interface {
	SendAudits([]Event) error
	Close() error
	fmt.Stringer
}

For contributions of new sinks, you can follow this pattern:

• Create a folder for your new sink under the audit package with a meaningful name of your sink
• Provide the implementation to how to send audit events to your sink via the SendAudits
• Provide the implementation of closing resources/connections to your sink via the Close method (this will be called asynchronously to the SendAudits method so account for that in your implementation)
• Provide the variables for configuration just like here for connection details to your sink
• Add a conditional to see if your sink is enabled here
• Write respective tests

🚀 you should be good to go!

Need help? Reach out to us on GitHub, Discord, Twitter, or Mastodon.

Documentation

Index

• type Actor
• type Checker
  • func NewChecker(eventPairs []string) (*Checker, error)
  • func (c *Checker) Check(eventPair string) bool
  • func (c *Checker) Events() []string
• type Constraint
  • func NewConstraint(c *flipt.Constraint) *Constraint
• type Distribution
  • func NewDistribution(d *flipt.Distribution) *Distribution
• type Event
  • func NewEvent(r flipt.Request, actor *Actor, payload interface{}) *Event
  • func (e *Event) AddToSpan(ctx context.Context)
  • func (e *Event) CopyInto(out *Event)
  • func (e Event) DecodeToAttributes() []attribute.KeyValue
  • func (e Event) MarshalLogObject(enc zapcore.ObjectEncoder) error
  • func (e *Event) PayloadToMap() (map[string]any, error)
  • func (e *Event) Valid() bool
• type EventExporter
  • func NewSinkSpanExporter(logger *zap.Logger, sinks []Sink) EventExporter
• type EventPairChecker
• type Flag
  • func NewFlag(f *flipt.Flag) *Flag
• type Metadata
• type Namespace
  • func NewNamespace(n *flipt.Namespace) *Namespace
• type NoOpChecker
  • func (n *NoOpChecker) Check(eventPair string) bool
  • func (n *NoOpChecker) Events() []string
• type Rollout
  • func NewRollout(r *flipt.Rollout) *Rollout
• type RolloutSegment
• type RolloutThreshold
• type Rule
  • func NewRule(r *flipt.Rule) *Rule
• type Segment
  • func NewSegment(s *flipt.Segment) *Segment
• type Sink
• type SinkSpanExporter
  • func (s *SinkSpanExporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error
  • func (s *SinkSpanExporter) SendAudits(ctx context.Context, es []Event) error
  • func (s *SinkSpanExporter) Shutdown(ctx context.Context) error
• type Variant
  • func NewVariant(v *flipt.Variant) *Variant

Types

type Actor

type Actor struct {
	Authentication string `json:"authentication,omitempty" avro:"authentication"`
	IP             string `json:"ip,omitempty" avro:"ip"`
	Email          string `json:"email,omitempty" avro:"email"`
	Name           string `json:"name,omitempty" avro:"name"`
	Picture        string `json:"picture,omitempty" avro:"picture"`
}

type Checker

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

Checker holds a map that maps event pairs to a dummy struct. It is basically used as a set to check for existence.

func NewChecker

func NewChecker(eventPairs []string) (*Checker, error)

NewChecker is the constructor for a Checker.

func (*Checker) Check

func (c *Checker) Check(eventPair string) bool

Check checks if an event pair exists in the Checker data structure for event emission.

func (*Checker) Events

func (c *Checker) Events() []string

Events returns the type of events we would like to emit to configured sinks.

type Constraint

type Constraint struct {
	Id           string `json:"id"`
	SegmentKey   string `json:"segment_key"`
	Type         string `json:"type"`
	Property     string `json:"property"`
	Operator     string `json:"operator"`
	Value        string `json:"value"`
	NamespaceKey string `json:"namespace_key"`
}

func NewConstraint

func NewConstraint(c *flipt.Constraint) *Constraint

type Distribution

type Distribution struct {
	Id        string  `json:"id"`
	RuleId    string  `json:"rule_id"`
	VariantId string  `json:"variant_id"`
	Rollout   float32 `json:"rollout"`
}

func NewDistribution

func NewDistribution(d *flipt.Distribution) *Distribution

type Event

type Event struct {
	Version string `json:"version" avro:"version"`

	Type string `json:"type" avro:"type"`

	Action string `json:"action" avro:"action"`

	Metadata Metadata `json:"metadata" avro:"metadata"`

	Payload interface{} `json:"payload" avro:"payload"`

	Timestamp string `json:"timestamp" avro:"timestamp"`

	Status string `json:"status" avro:"status"`
}

Event holds information that represents an action that was attempted in the system.

func NewEvent

func NewEvent(r flipt.Request, actor *Actor, payload interface{}) *Event

NewEvent is the constructor for an event.

func (*Event) AddToSpan

func (e *Event) AddToSpan(ctx context.Context)

func (*Event) CopyInto

func (e *Event) CopyInto(out *Event)

func (Event) DecodeToAttributes

func (e Event) DecodeToAttributes() []attribute.KeyValue

DecodeToAttributes provides a helper method for an Event that will return a value compatible to a SpanEvent.

func (Event) MarshalLogObject

func (e Event) MarshalLogObject(enc zapcore.ObjectEncoder) error

func (*Event) PayloadToMap

func (e *Event) PayloadToMap() (map[string]any, error)

func (*Event) Valid

func (e *Event) Valid() bool

type EventExporter

type EventExporter interface {
	ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error
	Shutdown(ctx context.Context) error
	SendAudits(ctx context.Context, es []Event) error
}

EventExporter provides an API for exporting spans as Event(s).

func NewSinkSpanExporter

func NewSinkSpanExporter(logger *zap.Logger, sinks []Sink) EventExporter

NewSinkSpanExporter is the constructor for a SinkSpanExporter.

type EventPairChecker

type EventPairChecker interface {
	Check(eventPair string) bool
	Events() []string
}

EventPairChecker is the contract for checking if an event pair exists and if it should be emitted to configured sinks.

type Flag

type Flag struct {
	Key            string `json:"key"`
	Name           string `json:"name"`
	Description    string `json:"description"`
	Enabled        bool   `json:"enabled"`
	NamespaceKey   string `json:"namespace_key"`
	DefaultVariant string `json:"default_variant,omitempty"`
}

func NewFlag

func NewFlag(f *flipt.Flag) *Flag

type Metadata

type Metadata struct {
	Actor *Actor `json:"actor,omitempty" avro:"actor"`
}

Metadata holds information of what metadata an event will contain.

type Namespace

type Namespace struct {
	Key         string `json:"key"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Protected   bool   `json:"protected"`
}

func NewNamespace

func NewNamespace(n *flipt.Namespace) *Namespace

type NoOpChecker

type NoOpChecker struct{}

func (*NoOpChecker) Check

func (n *NoOpChecker) Check(eventPair string) bool

func (*NoOpChecker) Events

func (n *NoOpChecker) Events() []string

type Rollout

type Rollout struct {
	NamespaceKey string            `json:"namespace_key"`
	FlagKey      string            `json:"flag_key"`
	Rank         int32             `json:"rank"`
	Description  string            `json:"description"`
	Threshold    *RolloutThreshold `json:"threshold,omitempty"`
	Segment      *RolloutSegment   `json:"segment,omitempty"`
}

func NewRollout

func NewRollout(r *flipt.Rollout) *Rollout

type RolloutSegment

type RolloutSegment struct {
	Key   string `json:"key"`
	Value bool   `json:"value"`
}

type RolloutThreshold

type RolloutThreshold struct {
	Percentage float32 `json:"percentage"`
	Value      bool    `json:"value"`
}

type Rule

type Rule struct {
	Id            string          `json:"id"`
	FlagKey       string          `json:"flag_key"`
	SegmentKey    string          `json:"segment_key"`
	Distributions []*Distribution `json:"distributions"`
	Rank          int32           `json:"rank"`
	NamespaceKey  string          `json:"namespace_key"`
}

func NewRule

func NewRule(r *flipt.Rule) *Rule

type Segment

type Segment struct {
	Key          string        `json:"key"`
	Name         string        `json:"name"`
	Description  string        `json:"description"`
	Constraints  []*Constraint `json:"constraints"`
	MatchType    string        `json:"match_type"`
	NamespaceKey string        `json:"namespace_key"`
}

func NewSegment

func NewSegment(s *flipt.Segment) *Segment

type Sink

type Sink interface {
	SendAudits(context.Context, []Event) error
	io.Closer
	fmt.Stringer
}

Sink is the abstraction for various audit sink configurations that Flipt will support.

type SinkSpanExporter

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

SinkSpanExporter sends audit logs to configured sinks through intercepting span events.

func (*SinkSpanExporter) ExportSpans

func (s *SinkSpanExporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error

ExportSpans completes one part of the implementation of a SpanExporter. Decodes span events to audit events.

func (*SinkSpanExporter) SendAudits

func (s *SinkSpanExporter) SendAudits(ctx context.Context, es []Event) error

SendAudits wraps the methods of sending audits events to various sinks.

func (*SinkSpanExporter) Shutdown

func (s *SinkSpanExporter) Shutdown(ctx context.Context) error

Shutdown will close all the registered sinks.

type Variant

type Variant struct {
	Id           string `json:"id"`
	FlagKey      string `json:"flag_key"`
	Key          string `json:"key"`
	Name         string `json:"name"`
	Description  string `json:"description"`
	Attachment   string `json:"attachment"`
	NamespaceKey string `json:"namespace_key"`
}

func NewVariant

func NewVariant(v *flipt.Variant) *Variant