Observer (fjage 2.6.0 API)

java.lang.Object
- org.arl.fjage.Agent
- - org.arl.fjage.observer.Observer

All Implemented Interfaces:

java.lang.Runnable, MessageListener, Messenger, TimestampProvider
```
public class Observer
extends Agent
implements MessageListener
```
An agent that observes all messages passing through its container, and publishes them over a web socket for consumption by a web based debugging interface.
To use, simply add the agent to a container:
```
 container.add("observer", new Observer());
 
```
The web interface is served by the application's own web server if it has one, and on DEFAULT_PORT otherwise. Pass a port explicitly to override that:
```
 container.add("observer", new Observer(8082));
 
```
The URL to browse to is logged when the agent starts, and is readable as the url parameter of the agent.
The agent installs a MessageListener on the container. The listener never consumes a message, and never throws, and so observation is transparent to the agents being observed. Since the listener is called before delivery is attempted, the observer sees messages that are sent, not messages that are successfully delivered. A message sent to a topic is seen once, addressed to the topic, and not once per subscriber.
An observer only sees traffic in its own container. In a distributed setup, add one observer per container.
Messages are serialized using the same JSON representation that remote containers and gateways use, wrapped in an envelope carrying a sequence number and timestamps:
```
 {"time": 1767225600000, "ptime": 12345, "seq": 7,
  "action": "send", "message": {"clazz": "...", "data": {...}}}
 
```
One JSON object is published per line.
The agent also tracks the endpoints (agents and topics) it has seen traffic to or from, and publishes that list to the web interface, which uses it to let the user choose what to display. Endpoints are discovered before any filtering is applied, so the list is complete even when messages are being dropped.
Since fjåge containers can be chatty, messages may be filtered in the container, before serialization, using an ObserverFilter. The filter may be set programmatically, or from the web interface. It is common to all connected web clients.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

protected static class Observer.Endpoint
An endpoint the observer has seen traffic to or from, and how much of it.

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`Observer.Endpoint` An endpoint the observer has seen traffic to or from, and how much of it.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`AUTO_PORT` Port setting denoting that the application's web server is to be used.
`protected WebSocketHubConnector`	`conn`
`protected java.lang.String`	`context`
`protected java.util.concurrent.atomic.AtomicLong`	`count`
`protected java.lang.Thread`	`ctrlThread`
`static java.lang.String`	`DEFAULT_CONTEXT` Default context path for the web interface.
`static int`	`DEFAULT_MAX_RATE` Default maximum number of messages published per second.
`static int`	`DEFAULT_PORT` Port used for the web interface when no port is specified and the application does not already run a web server.
`protected java.util.concurrent.atomic.AtomicLong`	`dropped`
`protected boolean`	`enabled`
`protected java.util.Map<java.lang.String,Observer.Endpoint>`	`endpoints`
`protected ObserverFilter`	`filter`
`protected com.google.gson.Gson`	`gson`
`protected java.util.List<org.eclipse.jetty.server.handler.ContextHandler>`	`handlers`
`protected long`	`lastStats`
`protected long`	`lastStatsCount`
`protected long`	`lastStatsDropped`
`protected int`	`maxRate`
`protected java.io.OutputStream`	`out`
`protected Platform`	`pf`
`protected int`	`port`
`protected static java.lang.String`	`RESOURCE`
`protected long`	`seq`
`protected WebServer`	`server`
`protected static long`	`STATS_INTERVAL`
`protected int`	`windowCount`
`protected long`	`windowStart`
`protected java.lang.Object`	`wlock`

Fields inherited from class org.arl.fjage.Agent
ALL, BLOCKING, FINE, FINER, FINEST, ignoreExceptions, INFO, log, NON_BLOCKING, OFF, SEVERE, thread, tid, WARNING

Constructor Summary

Constructors
Constructor and Description
`Observer()` Creates an observer agent serving a web interface on the same port as the application's web server, if it has one, and on `DEFAULT_PORT` otherwise.
`Observer(int port)` Creates an observer agent serving a web interface on a specified port.
`Observer(int port, java.lang.String context)` Creates an observer agent serving a web interface on a specified port and context path.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected boolean`	`allow(long t)` Rate limiter, called with wlock held.
`protected int`	`appPort()` Port of the application's web server, so that the observer can share it rather than open a port of its own.
`void`	`clearEndpoints()` Forgets the endpoints seen so far, and tells the web interface to do the same.
`protected void`	`discover(Message msg)` Notes the endpoints involved in a message, publishing any newly seen ones.
`int`	`getConnections()`
`long`	`getCount()`
`long`	`getDropped()`
`boolean`	`getEnabled()`
`java.lang.String[]`	`getEndpoints()` Gets the endpoints (agents and topics) that the observer has seen traffic to or from.
`ObserverFilter`	`getFilter()` Gets the filter currently applied to observed messages.
`int`	`getMaxRate()`
`java.lang.String`	`getUrl()`
`protected void`	`handleControl(java.lang.String s)`
`void`	`init()` Called by the container when the agent is started.
`boolean`	`onReceive(Message msg)` Called by the container for every message sent.
`protected void`	`publish(java.lang.String json)` Publishes a line to all connected web clients, called with wlock held.
`protected void`	`publishEndpoints(java.util.List<java.lang.String> subset)` Publishes the endpoints seen so far, or a subset of newly seen ones.
`protected void`	`publishSafely(java.lang.String json)` Publishes a line to all connected web clients, swallowing any error.
`protected void`	`publishState()`
`protected void`	`publishStats()`
`protected java.lang.String`	`serialize(Message msg, long t, long n)` Serializes a message, wrapped in an observer envelope.
`boolean`	`setEnabled(boolean b)`
`void`	`setFilter(ObserverFilter f)` Sets the filter to apply to observed messages, in the container, before serialization.
`int`	`setMaxRate(int r)`
`void`	`shutdown()` Called by the container when the agent is terminated.
`protected void`	`startControlThread()` Web clients share a single input stream on the hub connector, and there is no way to reply to an individual client.
`java.lang.String`	`toString()` Gets a string representation of the agent.

Methods inherited from class org.arl.fjage.Agent
add, agent, agentForService, agentForService, agentsForService, agentsForService, block, block, clone, currentTimeMillis, delay, deregister, deregister, die, getAgentID, getContainer, getName, getPlatform, getState, getStore, getType, getYieldDuringReceive, nanoTime, platformSend, prepareRequest, println, receive, receive, receive, receive, receive, receive, receive, receive, register, register, request, request, run, send, setLogLevel, setQueueSize, setYieldDuringReceive, stop, subscribe, topic, topic, topic, topic, topic, topic, unsubscribe, wake

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_PORT
```
public static final int DEFAULT_PORT
```
    Port used for the web interface when no port is specified and the application does not already run a web server.
    
    See Also:
    
    Constant Field Values
  - AUTO_PORT
```
public static final int AUTO_PORT
```
    Port setting denoting that the application's web server is to be used.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_CONTEXT
```
public static final java.lang.String DEFAULT_CONTEXT
```
    Default context path for the web interface.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_RATE
```
public static final int DEFAULT_MAX_RATE
```
    Default maximum number of messages published per second.
    
    See Also:
    
    Constant Field Values
  - RESOURCE
```
protected static final java.lang.String RESOURCE
```
    See Also:
    
    Constant Field Values
  - STATS_INTERVAL
```
protected static final long STATS_INTERVAL
```
    See Also:
    
    Constant Field Values
  - port
```
protected int port
```
  - context
```
protected final java.lang.String context
```
  - gson
```
protected final com.google.gson.Gson gson
```
  - wlock
```
protected final java.lang.Object wlock
```
  - endpoints
```
protected final java.util.Map<java.lang.String,Observer.Endpoint> endpoints
```
  - server
```
protected WebServer server
```
  - conn
```
protected WebSocketHubConnector conn
```
  - out
```
protected java.io.OutputStream out
```
  - handlers
```
protected java.util.List<org.eclipse.jetty.server.handler.ContextHandler> handlers
```
  - ctrlThread
```
protected java.lang.Thread ctrlThread
```
  - pf
```
protected Platform pf
```
  - enabled
```
protected volatile boolean enabled
```
  - maxRate
```
protected volatile int maxRate
```
  - filter
```
protected volatile ObserverFilter filter
```
  - count
```
protected final java.util.concurrent.atomic.AtomicLong count
```
  - dropped
```
protected final java.util.concurrent.atomic.AtomicLong dropped
```
  - seq
```
protected long seq
```
  - windowStart
```
protected long windowStart
```
  - windowCount
```
protected int windowCount
```
  - lastStats
```
protected long lastStats
```
  - lastStatsCount
```
protected long lastStatsCount
```
  - lastStatsDropped
```
protected long lastStatsDropped
```
- Constructor Detail
  - Observer
```
public Observer()
```
    Creates an observer agent serving a web interface on the same port as the application's web server, if it has one, and on DEFAULT_PORT otherwise. The port is resolved when the agent starts, so that it does not matter whether the application's web server is created before or after the observer is added to the container.
  - Observer
```
public Observer(int port)
```
    Creates an observer agent serving a web interface on a specified port.
    
    Parameters:
    
    port - port to serve the web interface on, or AUTO_PORT to use the application's web server.
  - Observer
```
public Observer(int port,
                java.lang.String context)
```
    Creates an observer agent serving a web interface on a specified port and context path.
    
    Parameters:
    
    port - port to serve the web interface on, or AUTO_PORT to use the application's web server.
    
    context - context path to serve the web interface at.
- Method Detail
  - init
```
public void init()
```
    Description copied from class: Agent
    
    Called by the container when the agent is started. This method is usually overridden by a class implementing an agent to initialize the agent and its behaviors.
    
    Overrides:
    
    init in class Agent
  - appPort
```
protected int appPort()
```
    Port of the application's web server, so that the observer can share it rather than open a port of its own. If more than one is running, the lowest numbered one is used, and if none is, DEFAULT_PORT.
  - shutdown
```
public void shutdown()
```
    Description copied from class: Agent
    
    Called by the container when the agent is terminated. This method may optionally be overridden to provide a clean up before termination.
    
    Overrides:
    
    shutdown in class Agent
  - onReceive
```
public boolean onReceive(Message msg)
```
    Called by the container for every message sent. Never consumes a message, and never throws.
    
    Specified by:
    
    onReceive in interface MessageListener
    
    Parameters:
    
    msg - received message.
    
    Returns:
    
    true if the message is consumed, false otherwise.
  - discover
```
protected void discover(Message msg)
```
    Notes the endpoints involved in a message, publishing any newly seen ones. This is cheap, since it does not serialize anything.
  - serialize
```
protected java.lang.String serialize(Message msg,
                                     long t,
                                     long n)
```
    Serializes a message, wrapped in an observer envelope. The message is serialized inline, on the calling agent's thread, since messages are delivered by reference within a container, and may be mutated by the recipient as soon as this method returns.
  - allow
```
protected boolean allow(long t)
```
    Rate limiter, called with wlock held.
  - publish
```
protected void publish(java.lang.String json)
                throws java.io.IOException
```
    Publishes a line to all connected web clients, called with wlock held.
    
    Throws:
    
    java.io.IOException
  - publishSafely
```
protected void publishSafely(java.lang.String json)
```
    Publishes a line to all connected web clients, swallowing any error.
  - publishEndpoints
```
protected void publishEndpoints(java.util.List<java.lang.String> subset)
```
    Publishes the endpoints seen so far, or a subset of newly seen ones.
    
    Parameters:
    
    subset - endpoint names to publish, null to publish the full list.
  - publishState
```
protected void publishState()
```
  - publishStats
```
protected void publishStats()
```
  - startControlThread
```
protected void startControlThread()
```
    Web clients share a single input stream on the hub connector, and there is no way to reply to an individual client. Control commands are therefore applied globally, and the resulting state is published to all clients.
  - handleControl
```
protected void handleControl(java.lang.String s)
```
  - getEnabled
```
public boolean getEnabled()
```
  - setEnabled
```
public boolean setEnabled(boolean b)
```
  - getCount
```
public long getCount()
```
  - getDropped
```
public long getDropped()
```
  - getMaxRate
```
public int getMaxRate()
```
  - setMaxRate
```
public int setMaxRate(int r)
```
  - getConnections
```
public int getConnections()
```
  - getUrl
```
public java.lang.String getUrl()
```
  - getFilter
```
public ObserverFilter getFilter()
```
    Gets the filter currently applied to observed messages.
    
    Returns:
    
    current filter.
  - setFilter
```
public void setFilter(ObserverFilter f)
```
    Sets the filter to apply to observed messages, in the container, before serialization.
    
    Parameters:
    
    f - filter to apply, null to observe all messages.
  - getEndpoints
```
public java.lang.String[] getEndpoints()
```
    Gets the endpoints (agents and topics) that the observer has seen traffic to or from.
    
    Returns:
    
    endpoint names, topics prefixed with #.
  - clearEndpoints
```
public void clearEndpoints()
```
    Forgets the endpoints seen so far, and tells the web interface to do the same. Since the list only ever grows, this is how to get rid of endpoints that are no longer around, such as gateways that have long since disconnected. Endpoints still in use reappear as soon as they send or receive anything.
  - toString
```
public java.lang.String toString()
```
    Description copied from class: Agent
    
    Gets a string representation of the agent.
    
    Overrides:
    
    toString in class Agent
    
    Returns:
    
    string representation of the agent.
    
    See Also:
    
    Object.toString()

Class Observer

Nested Class Summary

Field Summary

Fields inherited from class org.arl.fjage.Agent

Constructor Summary

Method Summary

Methods inherited from class org.arl.fjage.Agent

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_PORT

AUTO_PORT

DEFAULT_CONTEXT

DEFAULT_MAX_RATE

RESOURCE

STATS_INTERVAL

port

context

gson

wlock

endpoints

server

conn

out

handlers

ctrlThread

pf

enabled

maxRate

filter

count

dropped

seq

windowStart

windowCount

lastStats

lastStatsCount

lastStatsDropped

Constructor Detail

Observer

Observer

Observer

Method Detail

init

appPort

shutdown

onReceive

discover

serialize

allow

publish

publishSafely

publishEndpoints

publishState

publishStats

startControlThread

handleControl

getEnabled

setEnabled

getCount

getDropped

getMaxRate

setMaxRate

getConnections

getUrl

getFilter

setFilter

getEndpoints

clearEndpoints

toString