-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathquark_queue_open.3
159 lines (159 loc) · 4.2 KB
/
quark_queue_open.3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
.Dd $Mdocdate$
.Dt QUARK_QUEUE_OPEN 3
.Os
.Sh NAME
.Nm quark_queue_open
.Nd initialize a
.Vt quark_queue
.Sh SYNOPSIS
.In quark.h
.Ft int
.Fn quark_queue_open "struct quark_queue *qq" "struct quark_queue_attr *attr"
.Sh DESCRIPTION
.Nm
initializes the
.Vt quark_queue
pointed to by
.Fa qq
with the attributes pointed to by
.Fa attr .
.Pp
A
.Vt quark_queue
is the main runtime datastructure of quark, it is loosely called a queue as it's
where events will originate from.
Events will be collected into the queue, buffered, aggregated and filtered if
necessary.
.Pp
The
.Nm
function does the following:
.Bl -bullet
.It
Attempts to use the best backend available unless otherwise especified.
This includes loading the EBPF programs for EBPF or the probes for KPROBES.
Only one backend is used and it defaults to EBPF and falls back to KPROBE.
.It
On its first call it will also initialize global host state, like BTF offsets
and HZ.
.It
Initializes the various lists and internal buffers of
.Fa qq .
.It
If KPROBES is selected, it initializes one perf-ring per-cpu in order to
collect process events, see
.Xr quark_queue_get_epollfd 3
and
.Xr quark_queue_block 3 .
.It
If EBPF is selected, it initializes an EBPF ringbuffer, support for
old style perf-rings with EBPF is currently not supported.
.It
Scrapes
.Pa /proc
for a snapshot of the existing processes in the system.
.Nm
is smart enough to open the rings before the scraping, as to be make sure no
process is lost.
These initial processes are available through
.Xr quark_process_iter 3 .
.El
.Pp
Default queue behaviour can be tweaked with
.Fa attr .
A default configuration for tweaking can be acquired via
.Xr quark_queue_default_attr 3 .
In case
.Fa attr
is NULL, the default configuration is used.
.Pp
.Fa struct quark_queue_attr
is defined as:
.Bd -literal -offset indent
struct quark_queue_attr {
int flags;
int max_length;
int cache_grace_time; /* in milliseconds */
int hold_time; /* in milliseconds */
...
};
.Ed
.Bl -tag -width "max_length"
.It Em flags
Bitmask of:
.Bl -tag -width QQ_THREAD_EVENTS
.It Dv QQ_EBPF
Enable the EBPF backend.
EBPF is attempted first and falls back to KPROBE if both were specified.
.It Dv QQ_KPROBE
Enable the KPROBE backend, see above.
.It Dv QQ_ALL_BACKENDS
Shorthand for (QQ_EBPF | QQ_KPROBE).
.It Dv QQ_THREAD_EVENTS
Include per-thread events, instead of per-process events.
This option will be removed in the future, but it may be useful for debugging.
.It Dv QQ_MIN_AGG
Don't aggregate
.Em fork ,
.Em exec
and
.Em exit ,
perform only minimal aggregation.
.It Dv QQ_ENTRY_LEADER
Include
.Em proc_entry_leader
and
.Em proc_entry_type
in
.Em quark_events .
Entry leader is how the process entered the system, it is disabled by default as
it is Elastic/ECS specific.
.El
.It Em max_length
The maximum size of the internal buffering queue in number of events.
.Pp
Quark buffers each event for a computed interval in order to sort and aggregate
multiple events into one.
The closer the queue is to being full, the smaller the interval: until quark
decides to not buffer events at all.
.It Em cache_grace_time
The grace period for removing an event from the cache.
.Pp
When a process exits, it is removed from the cache, but only after
.Em cache_grace_time ,
this gives the user a small window where it can still query a terminated process
via
.Xr quark_process_lookup 3 .
.It Em hold_time
How long to buffer (hold) an event before delivering it to the user via
.Xr quark_queue_get_event 3 .
.Pp
Events received from the backend are not immediately forwarded to the user, this
allows multiple events to be aggregated as well as ordered by time.
In case quark is overloaded, it will use a stepping function where
.Em hold_time
decreases the more loaded it is.
.Pp
Details are described in
.Xr quark 7 .
.El
.Sh RETURN VALUES
Zero on success, -1 otherwise and
.Va errno
is set.
In the case of an error, the internal state is cleared up and a
.Xr quark_queue_close 3
should NOT be issued.
.Sh SEE ALSO
.Xr quark_event_dump 3 ,
.Xr quark_process_lookup 3 ,
.Xr quark_queue_block 3 ,
.Xr quark_queue_close 3 ,
.Xr quark_queue_default_attr 3 ,
.Xr quark_queue_get_epollfd 3 ,
.Xr quark_queue_get_event 3 ,
.Xr quark_queue_get_stats 3 ,
.Xr quark 7 ,
.Xr quark-btf 8 ,
.Xr quark-mon 8 ,
.Xr quark-test 8