Package com.lightbend.cinnamon.meta

Class Identity

  • public class Identity
extends java.lang.Object
    General purpose identity for instrumented entities.

    Entities can be identified by class (only has a class), instance (has both class and name), or group (only has a name).

    Identities belong to a category, for grouping instruments into categories like 'actors' or 'dispatchers'. Expressed in plural form.

    Identities have a key, used for tags.

    Identities can be organised in hierarchies, where each identity can have a parent identity, for forming full identifier keys.

    Identities can be hidden, where they are in the hierarchy but not used.

    Identities can be marked as being 'unique', unique to this instance of Cinnamon, such as host name and application identifier.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Identity NONE
      Empty identity.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Identity.Builder builder()
      Create a new identity builder, based on this identity.
      protected Identity.Builder copyToBuilder​(Identity.Builder builder)  
      static Identity.Builder createFor​(java.lang.String category, java.lang.String key)
      Create a new identity builder.
      boolean equals​(java.lang.Object o)  
      java.lang.String getCategory()
      The category for this identity (used for grouping, expressed in plural form).
      java.lang.Class getEntityClass()
      The entity class for this identity.
      java.lang.String getEntityName()
      The entity name for this identity (for instance or group identities).
      java.lang.String getKey()
      The key for this identity (used for tags).
      java.lang.String getName()
      Get the entity name (for instance or group) otherwise get the entity class name.
      static <T> Identity.IdentityCache<T> getNewCache()  
      Identity getParent()
      The enclosing parent identity for this identity.
      java.util.Map<java.lang.String,​java.lang.String> getTags()
      The tags for this identity.
      boolean hasCategory()
      Whether this identity has an associated category (used for grouping, expressed in plural form).
      boolean hasEntityClass()
      Whether this identity has an associated entity class.
      boolean hasEntityName()
      Whether this identity has an associated entity name (for instance or group identities).
      int hashCode()  
      boolean hasKey()
      Whether this identity has an associated key (used for tags).
      boolean hasName()
      Whether this identity has an associated name (either entity name or entity class).
      boolean hasParent()
      Whether this identity has an enclosing parent identity.
      boolean isDestroyable()
      Whether instruments for this identity can be destroyed, once the entity for this identity has terminated in some way.
      boolean isUnique()
      Whether this identity is unique to this instance of Cinnamon, such as host name or application identifier.
      boolean isVisible()
      Whether this identity is visible, and should be included in metric keys or tags.
      static Identity ofClass​(java.lang.String category, java.lang.String key, java.lang.Class entityClass)
      Create a new identity with class only, and no parent identity.
      static Identity ofClass​(java.lang.String category, java.lang.String key, java.lang.Class entityClass, Identity parent)
      Create a new identity with class only.
      static Identity ofGroup​(java.lang.String entityName)
      Create a new identity with name only, and no category, key, or parent identity.
      static Identity ofGroup​(java.lang.String entityName, Identity parent)
      Create a new identity with name and parent only, no category or key.
      static Identity ofGroup​(java.lang.String category, java.lang.String key, java.lang.String entityName)
      Create a new identity with name only, and no parent identity.
      static Identity ofGroup​(java.lang.String category, java.lang.String key, java.lang.String entityName, Identity parent)
      Create a new identity with name only.
      static Identity ofInstance​(java.lang.Class entityClass, java.lang.String entityName)
      Create a new identity with both class and name, and no category or parent identity.
      static Identity ofInstance​(java.lang.String category, java.lang.String key, java.lang.Class entityClass, java.lang.String entityName)
      Create a new identity with both class and name, and no parent identity.
      static Identity ofInstance​(java.lang.String category, java.lang.String key, java.lang.Class entityClass, java.lang.String entityName, Identity parent)
      Create a new identity with both class and name.
      static Identity ofTag​(java.lang.String category, java.lang.String key, java.lang.String tag, Identity parent)
      Create a new identity with name only.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • NONE

        public static Identity NONE
        Empty identity.

    • Method Detail

      • createFor

        public static Identity.Builder createFor​(java.lang.String category,
                                         java.lang.String key)
        Create a new identity builder.
        Parameters:
        category - category for entity (plural form)
        key - key for entity (used in tags)
        Returns:
        new Identity.Builder to create identity

      • ofClass

        public static Identity ofClass​(java.lang.String category,
                               java.lang.String key,
                               java.lang.Class entityClass)
        Create a new identity with class only, and no parent identity. Identifies all instances in a class, so not destroyable.
        Parameters:
        category - category for entity (plural form)
        key - key for entity (used in tags)
        entityClass - class for entity
        Returns:
        new class Identity

      • ofClass

        public static Identity ofClass​(java.lang.String category,
                               java.lang.String key,
                               java.lang.Class entityClass,
                               Identity parent)
        Create a new identity with class only. Identifies all instances in a class, so not destroyable.
        Parameters:
        category - category for entity (plural form)
        key - key for entity (used in tags)
        entityClass - class for entity
        parent - enclosing parent identity
        Returns:
        new class Identity

      • ofInstance

        public static Identity ofInstance​(java.lang.Class entityClass,
                                  java.lang.String entityName)
        Create a new identity with both class and name, and no category or parent identity. Assumed to be an instance, therefore destroyable.
        Parameters:
        entityClass - class for entity
        entityName - instance name for entity
        Returns:
        new instance Identity

      • ofInstance

        public static Identity ofInstance​(java.lang.String category,
                                  java.lang.String key,
                                  java.lang.Class entityClass,
                                  java.lang.String entityName)
        Create a new identity with both class and name, and no parent identity. Assumed to be an instance, therefore destroyable.
        Parameters:
        category - category for entity (plural form)
        key - key for entity (used in tags)
        entityClass - class for entity
        entityName - instance name for entity
        Returns:
        new instance Identity

      • ofInstance

        public static Identity ofInstance​(java.lang.String category,
                                  java.lang.String key,
                                  java.lang.Class entityClass,
                                  java.lang.String entityName,
                                  Identity parent)
        Create a new identity with both class and name. Assumed to be an instance, therefore destroyable.
        Parameters:
        category - category for entity (plural form)
        key - key for entity (used in tags)
        entityClass - class for entity
        entityName - instance name for entity
        parent - enclosing parent identity
        Returns:
        new instance Identity

      • ofGroup

        public static Identity ofGroup​(java.lang.String entityName)
        Create a new identity with name only, and no category, key, or parent identity. Assumed to be a group of entities, so not destroyable.
        Parameters:
        entityName - group name for entity
        Returns:
        new group Identity

      • ofGroup

        public static Identity ofGroup​(java.lang.String entityName,
                               Identity parent)
        Create a new identity with name and parent only, no category or key. Assumed to be a group of entities, so not destroyable.
        Parameters:
        entityName - group name for entity
        parent - enclosing parent identity
        Returns:
        new group Identity

      • ofGroup

        public static Identity ofGroup​(java.lang.String category,
                               java.lang.String key,
                               java.lang.String entityName)
        Create a new identity with name only, and no parent identity. Assumed to be a group of entities, so not destroyable.
        Parameters:
        category - category for entity (plural form)
        key - key for entity (used in tags)
        entityName - group name for entity
        Returns:
        new group Identity

      • ofGroup

        public static Identity ofGroup​(java.lang.String category,
                               java.lang.String key,
                               java.lang.String entityName,
                               Identity parent)
        Create a new identity with name only. Assumed to be a group of entities, so not destroyable.
        Parameters:
        category - category for entity (plural form)
        key - key for entity (used in tags)
        entityName - group name for entity
        parent - enclosing parent identity
        Returns:
        new group Identity

      • ofTag

        public static Identity ofTag​(java.lang.String category,
                             java.lang.String key,
                             java.lang.String tag,
                             Identity parent)
        Create a new identity with name only. Assumed to be a group of entities, so not destroyable.
        Parameters:
        category - category for entity (plural form)
        key - key for entity
        tag - name of the group
        parent - enclosing parent identity
        Returns:
        new group Identity

      • hasEntityClass

        public boolean hasEntityClass()
        Whether this identity has an associated entity class.
        Returns:
        boolean whether a class is specified

      • getEntityClass

        public java.lang.Class getEntityClass()
        The entity class for this identity. May be null.
        Returns:
        Class for this identity, or null if not present

      • hasEntityName

        public boolean hasEntityName()
        Whether this identity has an associated entity name (for instance or group identities).
        Returns:
        boolean whether a name is specified

      • getEntityName

        public java.lang.String getEntityName()
        The entity name for this identity (for instance or group identities). May be null.
        Returns:
        String name for this identity, or null if not present

      • hasName

        public boolean hasName()
        Whether this identity has an associated name (either entity name or entity class).
        Returns:
        boolean whether a name is specified

      • getName

        public java.lang.String getName()
        Get the entity name (for instance or group) otherwise get the entity class name.
        Returns:
        String either the name or class name for this identity

      • hasCategory

        public boolean hasCategory()
        Whether this identity has an associated category (used for grouping, expressed in plural form).
        Returns:
        boolean whether a category is specified

      • getCategory

        public java.lang.String getCategory()
        The category for this identity (used for grouping, expressed in plural form). May be null.
        Returns:
        String category for this identity, or null if not present

      • hasKey

        public boolean hasKey()
        Whether this identity has an associated key (used for tags).
        Returns:
        boolean whether a key is specified

      • getKey

        public java.lang.String getKey()
        The key for this identity (used for tags). May be null.
        Returns:
        String key for this identity, or null if not present

      • getTags

        public java.util.Map<java.lang.String,​java.lang.String> getTags()
        The tags for this identity. Used in both the metric key and metric tags.
        Returns:
        Map<String, String> of tags.

      • hasParent

        public boolean hasParent()
        Whether this identity has an enclosing parent identity.
        Returns:
        boolean whether parent identity is specified

      • getParent

        public Identity getParent()
        The enclosing parent identity for this identity. May be null.
        Returns:
        Identity parent for this identity, or null if not present

      • isDestroyable

        public boolean isDestroyable()
        Whether instruments for this identity can be destroyed, once the entity for this identity has terminated in some way.

        Instance identities are destroyable, while class and group identities are assumed to be not destroyable given that other instances with the same identity could still continue to exist.

        Returns:
        boolean whether this identity is destroyable

      • isVisible

        public boolean isVisible()
        Whether this identity is visible, and should be included in metric keys or tags.
        Returns:
        boolean whether this identity is visible

      • isUnique

        public boolean isUnique()
        Whether this identity is unique to this instance of Cinnamon, such as host name or application identifier.
        Returns:
        boolean whether this identity is unique

      • builder

        public Identity.Builder builder()
        Create a new identity builder, based on this identity.
        Returns:
        new Identity.Builder to create new identity

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object