Skydive uses a subset of the Gremlin language as query language for topology and flow requests.
A Gremlin expression is a chain of steps that are evaluated from left to right. In the context of Skydive nodes stand for interfaces, ports, bridges, namespaces, etc. Links stand for any kind of relation between two nodes, ownership(host, netns, ovsbridge, containers), layer2, etc.
The following expression will return all the OpenvSwitch ports belonging to
an OpenvSwitch bridge named
The following expression will return all the k8s Pods belonging to the
k8s NameSpace named
The query has to be read as :
Greturns the topology Graph
Vstep returns all the nodes belonging the Graph
Hasstep returns only the node with the given metadata attributes
Outstep returns outgoing nodes
The Skydive implements a subset of the Gremlin language steps and adds “network analysis” specific steps.
V step returns the nodes belonging to the graph.
A node ID can be passed to the V step which will return the corresponding node.
E step returns the edges belonging to the graph.
A edge ID can be passed to the E step which will return the corresponding edge.
Has step filters out the nodes that don’t match the given metadata list.
can be applied either on nodes or edges.
HasEither step filters out the nodes that don’t match the given metadata list.
Has applies an
AND between each key/value,
HasEither applies an
HasEither can be applied either on nodes or edges.
The following expression will return nodes with either
Name equals to
type equal to
HasKey step filters out the nodes that don’t match the given key list.
can be applied either on nodes or edges.
In/Out steps returns either incoming, outgoing or neighbor nodes of
previously selected nodes.
Filters can be applied to these steps in order to select only the nodes
corresponding to the given metadata. In that case the step will act as a couple
Out/Has for example.
Descendants step get the children nodes of elements retrieved by the previous step.
Descendants takes also an optional depth parameter which repeats the call n times.
Is equal to:
InE/OutE/BothE steps returns the incoming/ougoing links.
Like for the
In/Out/Both steps metadata list can be passed directly as
parameters in order to filter links.
InV/OutV steps returns incoming, outgoing nodes attached to the previously
Dedup removes duplicated nodes/links or flows.
Dedup can take a parameter
in order to specify the field used for the deduplication.
Count returns the number of elements retrieved by the previous step.
Values returns the property value of elements retrieved by the previous step.
Keys returns the list of properties of the elements retrieved by the previous step.
Sum returns sum of elements, named ‘Name’, retrieved by the previous step.
When attribute ‘Name’ exists, must be integer type.
Limit limits the number of elements returned.
ShortestPathTo step returns the shortest path to node matching the given
Metadata predicate. This step returns a list of all the nodes traversed.
It is possible to filter the link traversed according to the given
predicate as a second parameter.
As/Select steps allows to store intermediate results in order to aggregate them later. It is useful to do
an union of two parts of the Graph.
The following expression retrieves all the nodes of
netns and stores the result in the variable
then select all the nodes of
device and stores the result in the variable
result2. Finally returns
an union of both results doing a
Select of the two variables.
SubGraph step returns a new Graph based on the previous steps. Step V or E can
be used to walk trough this new Graph.
At allows to set the time context of the Gremlin request. It means that
we can contextualize a request to a specific point of time therefore being
able to see how was the graph in the past.
Supported formats for time argument are :
- RFC1123 format
- Go Duration format
At takes also an optional duration parameter which allows to specify a
period of time in second for the lookup. This is useful especially when retrieving
Metrics step for more information.
Flows step returns flows of nodes where a capture has been started or of nodes
where the packets are coming from or going to.
The following Gremlin query returns the flows from the node
an sFlow capture has been started.
See the client section
in order to know how to start a capture from a Gremlin query.
From a flow step it is possible to get the node from where the packets are
coming or the node where packets are going to. Node steps are of course
In/Out flow steps.
Has step filters out the flows that don’t match the given attributes list.
Key can be any attributes of the Flow data structure :
Lt, Lte, Gt, Gte predicates can be used on numerical fields. See Flow Schema for further explanations.
Link, Network and Transport keys shall be matched with any of A or B by using OR operator.
Sort step sorts flows by the given field and requested order.
By default, the flows are in ascending order by their
DESC predicates can be used to specify ascending and descending order respectively.
Dedup step de-duplicates flows having the same TrackingID.
Metrics returns arrays of metrics of a set of flows or interfaces, grouped by
the flows UUIDs or Node IDs.
For flow metrics :
and for interface metrics :
Predicates which can be used with
Out* steps :
NE, matches graph elements for which metadata don’t match specified values
Within, matches graph elements for which metadata values match one member of the given array.
Without, matches graph elements for which metadata values don’t match any of the members of the given array.
Regex, matches graph elements for which metadata matches the given regular expression.
Please note that the Regex step is always using anchors, ^ and $ don’t have to be provided in the expression.