state.go

state.go - Overview

1. Overview

This file defines types and functions for managing and storing the state of Alertmanager, specifically silences and notification logs, using a database. It includes structures for storing state data, creating new state instances, and setting/getting state information.

2. Detailed Documentation

Type State

type State = cluster.State

• Purpose: Type alias for cluster.State from the github.com/prometheus/alertmanager/cluster package.
• Parameters: None
• Returns: None

Variable SilenceStateName

var (
 SilenceStateName = StateName{name: "silence"}
)

• Purpose: Defines the name for the silence state.
• Parameters: None
• Returns: None

Variable NFLogStateName

var (
 NFLogStateName = StateName{name: "nflog"}
)

• Purpose: Defines the name for the nflog state (Notification log).
• Parameters: None
• Returns: None

Variable ErrCodeAlertmanagerStateNotFound

var (
 ErrCodeAlertmanagerStateNotFound = errors.MustNewCode("alertmanager_state_not_found")
)

• Purpose: Defines a custom error code for when the Alertmanager state is not found.
• Parameters: None
• Returns: None

Type StoreableState

type StoreableState struct {
 bun.BaseModel `bun:"table:alertmanager_state"`

 types.Identifiable
 types.TimeAuditable
 Silences string `bun:"silences,nullzero"`
 NFLog string `bun:"nflog,nullzero"`
 OrgID string `bun:"org_id"`
}

• Purpose: Represents the structure for storing Alertmanager state data in a database. Includes fields for silences, notification logs, and organization ID.
• Parameters: None
• Returns: None

Function NewStoreableState

func NewStoreableState(orgID string) *StoreableState {
 return &StoreableState{
  Identifiable: types.Identifiable{
   ID: valuer.GenerateUUID(),
  },
  TimeAuditable: types.TimeAuditable{
   CreatedAt: time.Now(),
   UpdatedAt: time.Now(),
  },
  OrgID: orgID,
 }
}

• Purpose: Creates a new instance of StoreableState with the provided organization ID and initializes the ID, creation, and update timestamps.
• Parameters:
  • orgID (string): The organization ID to associate with the state.
• Returns:
  • *StoreableState: A pointer to the newly created StoreableState instance.

Function (*StoreableState) Set

func (s *StoreableState) Set(stateName StateName, state State) (int64, error) {
 marshalledState, err := state.MarshalBinary()
 if err != nil {
  return 0, err
 }
 encodedState := base64.StdEncoding.EncodeToString(marshalledState)

 switch stateName {
 case SilenceStateName:
  s.Silences = encodedState
 case NFLogStateName:
  s.NFLog = encodedState
 }

 s.UpdatedAt = time.Now()

 return int64(len(marshalledState)), nil
}

• Purpose: Sets the state (silence or nflog) for the StoreableState by marshalling, encoding and storing.
• Parameters:
  • stateName (StateName): The name of the state to set (either SilenceStateName or NFLogStateName).
  • state (State): The state data to be stored.
• Returns:
  • int64: The length of the marshalled state.
  • error: An error if marshalling or encoding fails.

Function (*StoreableState) Get

func (s *StoreableState) Get(stateName StateName) (string, error) {
 base64encodedState := ""

 switch stateName {
 case SilenceStateName:
  base64encodedState = s.Silences
 case NFLogStateName:
  base64encodedState = s.NFLog
 }

 if base64encodedState == "" {
  return "", errors.New(errors.TypeNotFound, ErrCodeAlertmanagerStateNotFound, "state not found")
 }

 decodedState, err := base64.StdEncoding.DecodeString(base64encodedState)
 if err != nil {
  return "", err
 }

 return string(decodedState), nil
}

• Purpose: Retrieves the state (silence or nflog) from the StoreableState by decoding and unmarshalling.
• Parameters:
  • stateName (StateName): The name of the state to retrieve (either SilenceStateName or NFLogStateName).
• Returns:
  • string: The decoded state data as a string.
  • error: An error if the state is not found or decoding fails.

Type StateName

type StateName struct {
 name string
}

• Purpose: Represents the name of a state (e.g., "silence", "nflog").
• Parameters: None
• Returns: None

Function (StateName) String

func (s StateName) String() string {
 return s.name
}

• Purpose: Returns the string representation of the StateName.
• Parameters: None
• Returns:
  • string: The name of the state.

Type StateStore

type StateStore interface {
 // Creates the silence or the notification log state and returns the number of bytes in the state.
 // The return type matches the return of `silence.Maintenance` or `nflog.Maintenance`.
 // See https://github.com/prometheus/alertmanager/blob/3b06b97af4d146e141af92885a185891eb79a5b0/silence/silence.go#L217
 // and https://github.com/prometheus/alertmanager/blob/3b06b97af4d146e141af92885a185891eb79a5b0/nflog/nflog.go#L94
 Set(context.Context, string, *StoreableState) error

 // Gets the silence state or the notification log state as a string from the store. This is used as a snapshot to load the
 // initial state of silences or notification log when starting the alertmanager.
 Get(context.Context, string) (*StoreableState, error)
}

• Purpose: Defines the interface for interacting with a state store. It provides methods to set and get the Alertmanager state.
• Parameters: None
• Returns: None

Function Set (from StateStore interface)

Set(context.Context, string, *StoreableState) error

• Purpose: Sets the silence or notification log state.
• Parameters:
  • context.Context: Context for the operation.
  • string: orgID.
  • *StoreableState: The state to be stored.
• Returns:
  • error: An error if the operation fails.

Function Get (from StateStore interface)

Get(context.Context, string) (*StoreableState, error)

• Purpose: Gets the silence state or the notification log state.
• Parameters:
  • context.Context: Context for the operation.
  • string: orgID.
• Returns:
  • *StoreableState: The stored state.
  • error: An error if the operation fails.

3. Code Examples

Not applicable.

4. Clarity and Accuracy

The documentation is based on the provided code.

5. Markdown & MDX Perfection

No issues.

6. Edge Cases To Avoid Breaking MDX

No issues.

Include in Getting Started: NO