Consumer example

With the help of Bork, consumers can inform them selfs or be informed of the availability of a particular agent or of agents with certain properties. With running instances of Orion Context Broker, Bork and a minimum of one agent, the following scenarios can be passed through.

With a particular agent

When the consumer is aware of a particular agent, he can query his availability informations directly. For example, an agent identified by "id": "IML:SAN-123a", type": "Agent", servicePath": "/iml" and "service": "t_01". If the multi tenancy and hierarchical scopes are not used, the corresponding attributes can be omitted.

curl "http://localhost:1026/v2/entities?type=MonitoredAgent&q=refAgent.type==Agent;refAgent.id==IML:SAN-123a;refAgent.servicePath==/iml;refAgent.service==t_01&options=keyValues&attrs=*,dateCreated,dateModified"

{
    "id": "IML:SAN-123a",
    "type": "MonitoredAgent",
    "refAgent": {
        "id": "IML:SAN-123a",
        "type": "Agent",
        "servicePath": "/iml",
        "service": "t_01"
    },
    "agentCategory": "SAN",
    "agentCapabilities": ["pressure" , "temperature"],
    "isAvailable": true,
    ...
}

For the other properties of the MonitoredAgent entity, see schema documentation.

With several particular agents

This procedure can only be used if the servicePath and service of theses agents are the same.

curl "http://localhost:1026/v2/entities?type=MonitoredAgent&q=refAgent.type==Agent;refAgent.id==IML:SAN-123a,IML:SAN-123b;refAgent.servicePath==/iml;refAgent.service==t_01&options=keyValues&attrs=*,dateCreated,dateModified"

{
    {
        "id": "IML:SAN-123a",
        "type": "MonitoredAgent",
        "refAgent": {
            "id": "IML:SAN-123a",
            "type": "Agent",
            "servicePath": "/iml",
            "service": "t_01"
        },
        "agentCategory": "SAN",
        "agentCapabilities": ["pressure" , "temperature"],
        "isAvailable": true,
        ...
    },
    {
        "id": "IML:SAN-123b",
        "type": "MonitoredAgent",
        "refAgent": {
            "id": "IML:SAN-123b",
            "type": "Agent",
            "servicePath": "/iml",
            "service": "t_01"
        },
        "agentCategory": "SAN",
        "agentCapabilities": ["pressure" , "temperature"],
        "isAvailable": false,
        ...
    }
}

With agents that are compliant to certain properties

For example, a consumer can discover an agent with certain capabilities and metrics. This enables a QoS-based service discovery. This could be a consumer searching for a sensor that measures the temperature that is currently marked as available by Bork, that has a relative uptime above 95 percent and a mean time to recovery that is less than 5 seconds.

curl "http://localhost:1026/v2/entities?type=MonitoredAgent&q=isAvailable==true;agentCapabilities==temperature;relativeUptime>0.95;mttr<5&options=keyValues&attrs=*,dateCreated,dateModified"

{
    "id": "IML:SAN-123a",
    "type": "MonitoredAgent",
    "refAgent": {
        "id": "IML:SAN-123a",
        "type": "Agent",
        "servicePath": "/iml",
        "service": "t_01"
    },
    "agentCategory": "SAN",
    "agentCapabilities": ["pressure" , "temperature"],
    "isAvailable": true,
    "relativeUptime": 0.98,
    "mttr": 1.6,
    ...
}

If needed, with the help of this received MonitoredAgent entity the consumer can inspect the previously unknown referenced agent, that is specified in the attribute refAgent.

Continuous information through a subscription

The result of the above queries can also be achieved by subscriptions, with the benefit that the consumer is informed of availability changes of the certain agent/agents. The last stated query can be realized as a subscriptions as follows.

<Method: 'POST'> <Headers: '{'Content-Type': 'application/json', 'Fiware-Service': 't_01', 'Fiware-ServicePath': '/iml/#'}'> <URL: 'http://localhost:1026/v2/subscriptions'>

{
    "description": "Consumers MonitoredAgent Subscription for a sensor that measures the temperature, that is currently marked as available by Bork, that has a relative uptime above 95 percent and a mean time to recovery that is less than 5 seconds",
    "subject": {
        "entities": [
            {
                "idPattern": ".+",
                "type": "MonitoredAgent"
            }
        ],
        "condition": {
            "expression": {
                "q": "isAvailable==true;agentCapabilities==temperature;relativeUptime>0.95;mttr<5"
            }
        }
    },
    "notification": {
        "http": {
            "url": "http://localhost:54321/agentUpdates"
        },
        "attrs": [
            "*",
            "dateCreated",
            "dateModified"
        ],
        "attrsFormat": "keyValues"
    }
}

Note: Subscriptions with Fiware-ServicePath are only affected by entities in the exact same path. Adding a tailing # to the path allows the subscription to be affected by all entities in underneath paths, see fiware-orion.readthedocs.

The continuous information received by this subscription enables the consumer to react to availability changes of the used agent/agents. For this use case the better granulated availability indicating property status can be used. The following timing diagram shows the time at which the consumer changes the agent.

Timing Diagram

As shown, the property status can alternate between trusted, suspected and toDelete. Combined with the above subscription, for example when the status drops to suspected, the consumer can look up wich of the from the subscription affected agents has the same capability and can comply with the needed metrics. If the status drops to toDelete the consumer could then change to this other agent, which may have worse metrics, but nevertheless can provide the same capabilities.

Without time assumptions

If the agent runs using the Mode 1, that means he doesn't support time assumptions, the properties detectionTimeUpperBound, mistakeRecurrenceTimeLowerBound and mistakeDurationUpperBound wont be part of the MonitoredAgent entity. In this Mode the consumer can't know exactly which period Bork uses to suspect the agent. In addition, this period can be longer than the one the consumer considers tolerable. For example, the consumer runs a subroutine that depends on the contextual informations of an agent, but that subroutine should be done after a maximum of 3 seconds. Because the timeout period is adaptively calculated by Bork the time after which Bork suspects the particular agent can exceed 3 seconds. So if the property currentNotifyInterval in terms of value was at the beginning still 2, this does not mean this value will not raise or fall.

The consumer could monitor the currentNotifyInterval, which plus a safety margin is the timeout interval used by Bork, to know approximately when Bork will suspect the agent. This could be used if a rough estimation is needed.

With time assumptions

If the agent runs using the Mode 2, that means he does support time assumptions, the properties detectionTimeUpperBound, mistakeRecurrenceTimeLowerBound and mistakeDurationUpperBound are part of the MonitoredAgent entity. As described in the schema documentation, these properties reflect the bounds in which the failure detection will work. The only interesting attribute for the agent is the detectionTimeUpperBound. Bork will calculate a notifyIntervall with the other both properties, that complies with the detectionTimeUpperBound. This notifyIntervall is used by the particular agent. With that the consumer has the time that maximal elapses from the beginning of a crash of the agent, to the detection through Bork. For example, the consumer can calculate the timepoint at wich Bork will suspect a particular Agent just with dateModified + detectionTimeUpperBound. With this time assumption the consumer exactly knows how long he has to wait at most for Bork's conclusion. The whole thing leads to the fact that a consumer that must run many subroutines in a short time can discover a agent that can serve a suitable detectionTimeUpperBound.

Multi tenancy and hierarchical scopes

Bork supports Orion Context Broker's multi tenancy capability and hierarchical scopes. This means that a consumer must be aware, that the MonitoredAgent entity is located in the same path as the associated Agent entity. Adding a tailing # to a general subscription, as noted in the Continuous information through a subscription section, ensures that every MonitoredAgent entity in the underlying paths are addressed by the subscription. The Fiware-Service of these entities is the same as the one that Bork was configured with.