Entities

Entities describe what you want to monitor in your infrastructure. This can be as basic as a host, with its attributes hostname and IP; or something more complex, like a PostgreSQL sharded cluster with its identifier and set of connection strings.

ZMON gives you two options for automation in/integration with your platform: storing entities via zmon-controller’s entity service, or discovering them via the adapters in zmon-scheduler. At Zalando we use both, connecting ZMON to tools like our CMDB but also pushing entities via REST API.

ZMON’s entity service describes entities with a single JSON document.

  • Any entity must contain an ID that is unique within your ZMON deployment. We often use a pattern like <hostname>(:<port>) to create uniqueness at the host and application levels, but this is up to you.
  • Any entity must contain a type which describes the kind of entity, like an object class.

At the check execution we bind entity properties as default values to the functions executed, e.g. the IP gets used for relative http() requests.

Format

Generally, ZMON entity is a set of properties that can be represented as a multi-level dictionary. For example:

{
    "id":"arbitrary_entity_id",
    "type":"some_type",
    "oneMoreProperty":"foo",
    "nestedProperty": {
        "subProperty1": "foo",
        "subProperty2": "bar",
    }
}

2 notes here to keep in mind:

  1. id and type properties are mandatory.
  2. ZMON filtering (e.g. in ZMON UI) does not support nested properties.

Examples

In working with the Vagrant Box, you can use the scheduler instance entity like this:

{
    "id":"localhost:3421",
    "type":"instance",
    "host":"localhost",
    "project":"zmon-scheduler-ng",
    "ports": {"3421":3421}
}

Here, you can use the “ports” dictionary to also describe additional open ports. As with Spring Boot, a second port is usually added, exposing management features.

Now let’s look at an example of the PostgreSQL instance:

{
    "id":"localhost:5432",
    "type":"database",
    "name":"zmon-cluster",
    "shards": {"zmon":"localhost:5432/local_zmon_db"}
}

Usage of the property “shards” is given by how ZMON’s worker exposes PostgreSQL clusters to the sql() function.

View more examples here.

If you’d like to create an entity by yourself, check ZMON CLI tool