What is the filter_key in Nomad event stream API?

Nomad
1

The Nomad event stream api has this explanation for topic Events - HTTP API | Nomad | HashiCorp Developer :

As an example ?topic=Deployment:redis would subscribe to all Deployment events for a job redis. an additional topic &topic=Deployment:web would include deployment events for redis and web.

Great. Now what does mean Allocation:redis? Means to subscribe to allocation with ID redis or to allocation that belong to a job named redis? Is it the same with Evaluation:redis? Job:redis? What does it mean to listen to NodePool:redis? ACLToken:redis? What happen when namespace is *, then Job:redis would filter redis job from all namespaces?

Bottom line, what is the exact specification of “filter_key” in event stream?

Thanks!

2

Hi @Kamilcuk.

Bottom line, what is the exact specification of “filter_key” in event stream?

The Nomad documentation should certainly be improved to better detail this. Until the addition is ready, I would check the eventFromChange function.

The example below indicates that ACL Roles use the ID as the key, but include the Name as a filter key.

structs.Event{
    Topic:      structs.TopicACLRole,
    Key:        before.ID,
    FilterKeys: []string{before.Name},
    Payload: &structs.ACLRoleStreamEvent{
        ACLRole: before,
    },
}

I hope this helps in the short term, although it is absolutely less than ideal.

Thanks,
jrasell and the Nomad team

1 Like
3

Hi Jrasell! Thanks for the response!

From your helpful hints, I also see eventMatchesKey() and the above subscription.filter(). I note that eventMatchesKey() matches against Key and against all values in filterKeys and if any of the comparisons is true it returns true.

I’m trying to summarize. This is my understanding, would be great if someone would confirm.

In the Nomad event stream, the parameter filter_key is compared against several fields. Which fields depend on the chosen topic. If any of the comparisons is true, the event is sent. The comparison is done with exact string comparison.

Topic filter_key is compared with
job job.ID
alloc alloc.ID JobID DeploymentID
evaluation evaluation.ID JobID DeploymentID
nodes node.ID
deployment deployment.ID JobID

Etc. someone would have to create a full list with all the topics.

Thanks!