An Attributes is an immutable collection of Attribute[_] instances. It contains only unique keys and is used throughout otel4s to attach metadata to spans, metrics, and other telemetry data.
Type Signature
sealed trait Attributes extends immutable.Iterable[Attribute[_]]
Creating Attributes
apply
Attributes(attributes: Attribute[_]*): Attributes
Attributes with the given attributes.
Variable number of attributes to include
val attrs = Attributes(
Attribute("http.method", "GET"),
Attribute("http.status_code", 200L)
)
empty
Attributes.empty: Attributes
Attributes.
Example:
val attrs = Attributes.empty
fromSpecific
Attributes.fromSpecific(attributes: IterableOnce[Attribute[_]]): Attributes
Attributes from a collection.
attributes
IterableOnce[Attribute[_]]
required
The collection of attributes to use
Retrieving Attributes
get (by name)
def get[T: KeySelect](name: String): Option[Attribute[T]]
Attribute matching the given attribute name and type.
The name of the attribute
The type of the attribute value (must have a KeySelect instance)
Option[Attribute[T]] - Some(attribute) if found, None otherwise
Example:
val method: Option[Attribute[String]] = attrs.get[String]("http.method")
val statusCode: Option[Attribute[Long]] = attrs.get[Long]("http.status_code")
get (by key)
def get[T](key: AttributeKey[T]): Option[Attribute[T]]
Attribute matching the given attribute key.
Returns: Option[Attribute[T]] - Some(attribute) if found, None otherwise
Adding Attributes
added (by name)
def added[T: KeySelect](name: String, value: T): Attributes
Attribute with the given name and value, replacing any attribute with the same name and type if one exists.
The name of the attribute
The value of the attribute
Attributes - A new Attributes instance with the attribute added
Example:
val updated = attrs.added("http.url", "https://example.com")
added (by key)
def added[T](key: AttributeKey[T], value: T): Attributes
Attribute with the given key and value, replacing any attribute with the same key if one exists.
The value of the attribute
Attributes - A new Attributes instance with the attribute added
added (attribute)
def added(attribute: Attribute[_]): Attributes
Attribute, replacing any attribute with the same key if one exists.
Returns: Attributes - A new Attributes instance with the attribute added
+ operator
def +(attribute: Attribute[_]): Attributes
added(attribute).
Example:
val updated = attrs + Attribute("http.url", "https://example.com")
Combining Attributes
concat
def concat(that: IterableOnce[Attribute[_]]): Attributes
Attributes with another collection of attributes.
that
IterableOnce[Attribute[_]]
required
The attributes to concatenate
Attributes - A new Attributes instance with both sets of attributes
If multiple attributes have the same key, only the final one (according to that’s iterator) will be retained.
++ operator
def ++(that: IterableOnce[Attribute[_]]): Attributes
concat(that).
Example:
val attrs1 = Attributes(Attribute("key1", "value1"))
val attrs2 = Attributes(Attribute("key2", "value2"))
val combined = attrs1 ++ attrs2
Builder Pattern
newBuilder
Attributes.newBuilder: Attributes.Builder
Builder for constructing Attributes.
Example:
val builder = Attributes.newBuilder
builder.addOne("http.method", "GET")
builder.addOne("http.status_code", 200L)
val attrs = builder.result()
Builder Methods
class Builder {
def addOne[A: KeySelect](name: String, value: A): Builder
def addOne[A](key: AttributeKey[A], value: A): Builder
def addOne(attribute: Attribute[_]): Builder
def addAll(attributes: IterableOnce[Attribute[_]]): Builder
def result(): Attributes
def clear(): Unit
}
val attrs = Attributes.newBuilder
.addOne("service.name", "my-service")
.addOne("service.version", "1.0.0")
.addOne("deployment.environment", "production")
.result()
Custom Attribute Creation
Attributes.Make
The Attributes.Make[A] trait allows creating Attributes from arbitrary types.
trait Make[A] {
def make(a: A): Attributes
}
from
Attributes.from[A](value: A)(implicit make: Make[A]): Attributes
Attributes from a value using an implicit Make instance.
The value to convert to attributes
case class User(id: Long, group: String)
implicit val userAttributesMake: Attributes.Make[User] =
user => Attributes(
Attribute("user.id", user.id),
Attribute("user.group", user.group)
)
val attributes: Attributes = Attributes.from(User(1L, "admin"))
// Result: Attributes(Attribute("user.id", 1L), Attribute("user.group", "admin"))
Collection Operations
Since Attributes extends immutable.Iterable[Attribute[_]], you can use standard collection operations:
val attrs = Attributes(
Attribute("key1", "value1"),
Attribute("key2", 42L)
)
// Iterate
attrs.foreach(attr => println(attr))
// Map
val names = attrs.map(_.key.name)
// Filter
val stringAttrs = attrs.filter(_.key.`type` == AttributeType.String)
// Size
val count = attrs.size
// Check if empty
val isEmpty = attrs.isEmpty
Type Classes
Show
implicit val showAttributes: Show[Attributes]
Show instance for pretty-printing attributes.
Example:
import cats.syntax.show._
println(attrs.show)
// Output: Attributes(Attribute("http.method", "GET"), Attribute("http.status_code", 200))
Hash
implicit val hashAttributes: Hash[Attributes]
Hash instance for comparing attributes.
Monoid
implicit val monoidAttributes: Monoid[Attributes]
Monoid instance for combining attributes.
Example:
import cats.syntax.monoid._
val attrs1 = Attributes(Attribute("key1", "value1"))
val attrs2 = Attributes(Attribute("key2", "value2"))
val combined = attrs1 |+| attrs2
See Also
- Attribute - Individual attribute instances
- AttributeKey - Typed attribute keys
- Span - Using attributes with spans
- Meter - Using attributes with metrics