Skip to main content

labels.go

labels.go - Overview​

  1. Overview This file defines the Label and Labels types, along with related functions for manipulating labels, such as sorting, hashing, and converting between different representations (string, map, JSON). It also includes a Builder to modify labels efficiently.

  2. Detailed Documentation

Constants​

  • MetricNameLabel:
    • Purpose: Defines the well-known label name used by Prometheus components for the metric name.
  • TemporalityLabel:
    • Purpose: Defines the well-known label name for temporality.
  • AlertNameLabel:
    • Purpose: Defines the label name for alert name.
  • AlertStateLabel:
    • Purpose: Defines the label name indicating the state of an alert.
  • AlertRuleIdLabel:
    • Purpose: Defines the label name for the rule ID of an alert.
  • RuleSourceLabel:
    • Purpose: Defines the label name for the source of a rule.
  • RuleThresholdLabel:
    • Purpose: Defines the label name for the threshold of a rule.
  • AlertSummaryLabel:
    • Purpose: Defines the label name for the summary of an alert.
  • AlertDescriptionLabel:
    • Purpose: Defines the label name for the description of an alert.
  • sep:
    • Purpose: Defines a separator character used in hashing.

Type Label​

  • Purpose: Represents a key/value pair of strings.
  • Fields:
    • Name: The name of the label (string).
    • Value: The value of the label (string).

Type Labels​

  • Purpose: Represents a sorted set of labels.
  • Type: []Label

(ls Labels) Len() int​

  • Purpose: Returns the length of the Labels slice.
  • Parameters:
    • ls: The Labels slice.
  • Returns: The length of the slice (int).

(ls Labels) Swap(i, j int)​

  • Purpose: Swaps the elements at indices i and j in the Labels slice.
  • Parameters:
    • ls: The Labels slice.
    • i: The first index (int).
    • j: The second index (int).
  • Returns: None.

(ls Labels) Less(i, j int) bool​

  • Purpose: Compares the names of the labels at indices i and j. Returns true if the name at index i is less than the name at index j.
  • Parameters:
    • ls: The Labels slice.
    • i: The first index (int).
    • j: The second index (int).
  • Returns: True if ls[i].Name < ls[j].Name, false otherwise (bool).

(ls Labels) String() string​

  • Purpose: Returns a string representation of the Labels in the format {name1="value1", name2="value2", ...}.
  • Parameters:
    • ls: The Labels slice.
  • Returns: A string representation of the Labels (string).

(ls Labels) MarshalJSON() ([]byte, error)​

  • Purpose: Marshals the Labels into a JSON representation.
  • Parameters:
    • ls: The Labels slice.
  • Returns:
    • A JSON byte array representing the Labels ([]byte).
    • An error if marshalling fails (error).

(ls *Labels) UnmarshalJSON(b []byte) error​

  • Purpose: Unmarshals a JSON byte array into a Labels.
  • Parameters:
    • ls: A pointer to the Labels slice.
    • b: The JSON byte array ([]byte).
  • Returns: An error if unmarshalling fails (error).

(ls Labels) Hash() uint64​

  • Purpose: Calculates a hash value for the Labels.
  • Parameters:
    • ls: The Labels slice.
  • Returns: A hash value for the Labels (uint64).

(ls Labels) HashForLabels(b []byte, names ...string) (uint64, []byte)​

  • Purpose: Calculates a hash value for the labels matching the provided names.
  • Parameters:
    • ls: The Labels slice.
    • b: A byte slice to append the label data to.
    • names: A variadic list of label names to include in the hash.
  • Returns:
    • A hash value for the selected labels (uint64).
    • The modified byte slice b.

(ls Labels) HashWithoutLabels(names ...string) uint64​

  • Purpose: Calculates a hash value for all labels except those matching the provided names.
  • Parameters:
    • ls: The Labels slice.
    • names: A variadic list of label names to exclude from the hash.
  • Returns: A hash value for the Labels (uint64).

(ls Labels) Copy() Labels​

  • Purpose: Creates a copy of the Labels.
  • Parameters:
    • ls: The Labels slice.
  • Returns: A copy of the Labels (Labels).

(ls Labels) Get(name string) string​

  • Purpose: Retrieves the value of a label with the given name.
  • Parameters:
    • ls: The Labels slice.
    • name: The name of the label to retrieve.
  • Returns: The value of the label, or an empty string if the label is not found (string).

(ls Labels) Has(name string) bool​

  • Purpose: Checks if a label with the given name exists in the Labels.
  • Parameters:
    • ls: The Labels slice.
    • name: The name of the label to check for.
  • Returns: True if the label exists, false otherwise (bool).

Equal(ls, o Labels) bool​

  • Purpose: Checks if two Labels are equal.
  • Parameters:
    • ls: The first Labels.
    • o: The second Labels.
  • Returns: True if the Labels are equal, false otherwise (bool).

(ls Labels) Map() map[string]string​

  • Purpose: Converts the Labels to a string map.
  • Parameters:
    • ls: The Labels slice.
  • Returns: A string map representation of the Labels (map[string]string).

New(ls ...Label) Labels​

  • Purpose: Creates new sorted Labels from a variable number of Label arguments.
  • Parameters:
    • ls: A variadic list of Label.
  • Returns: Sorted Labels (Labels).

FromMap(m map[string]string) Labels​

  • Purpose: Creates new sorted Labels from a string map.
  • Parameters:
    • m: The string map.
  • Returns: Sorted Labels (Labels).

FromStrings(ss ...string) Labels​

  • Purpose: Creates new sorted Labels from pairs of strings.
  • Parameters:
    • ss: A variadic list of strings representing name-value pairs.
  • Returns: Sorted Labels (Labels).
  • Panics: If the number of strings is not even.

Compare(a, b Labels) int​

  • Purpose: Compares two Labels.
  • Parameters:
    • a: The first Labels.
    • b: The second Labels.
  • Returns:
    • 0 if a == b
    • < 0 if a < b
    • > 0 if a > b (int)

Type Builder​

  • Purpose: Allows modifying Labels.
  • Fields:
    • base: The original Labels (Labels).
    • del: A slice of label names to delete ([]string).
    • add: A slice of labels to add or update ([]Label).

NewBuilder(base Labels) *Builder​

  • Purpose: Creates a new LabelsBuilder.
  • Parameters:
    • base: The base Labels.
  • Returns: A pointer to the new Builder (*Builder).

(b *Builder) Del(ns ...string) *Builder​

  • Purpose: Deletes labels with the given names.
  • Parameters:
    • b: A pointer to the Builder.
    • ns: A variadic list of label names to delete.
  • Returns: A pointer to the Builder (*Builder).

(b *Builder) Set(n, v string) *Builder​

  • Purpose: Sets the value of a label with the given name.
  • Parameters:
    • b: A pointer to the Builder.
    • n: The name of the label.
    • v: The value of the label.
  • Returns: A pointer to the Builder (*Builder).

(b *Builder) Labels() Labels​

  • Purpose: Returns the modified Labels.
  • Parameters:
    • b: A pointer to the Builder.
  • Returns: The modified Labels (Labels).
  1. Code Examples
// Example of creating and using Labels
import labels from './labels';

// Create Labels from a map
const myLabels = labels.FromMap({
  'app': 'my-app',
  'version': '1.0'
});

console.log(myLabels.String()); // Output: {app="my-app", version="1.0"}

// Create a Builder
const builder = labels.NewBuilder(myLabels);
builder.Set('env', 'prod');
const newLabels = builder.Labels();

console.log(newLabels.String()); // Output: {app="my-app", env="prod", version="1.0"}

Include in Getting Started: YES