Skip to content

Commit d810e38

Browse files
phonebenphoneben
committed
Add AMI Event Filtering documentation
Add comprehensive guide for Advanced Event Filtering Include syntax, examples, and best practices Document legacy filtering method with deprecation note Resolves #160
1 parent 568d182 commit d810e38

File tree

2 files changed

+172
-5
lines changed

2 files changed

+172
-5
lines changed

‎docs/Configuration/Interfaces/Asterisk-Manager-Interface-AMI/AMI-v2-Specification/index.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1081,11 +1081,7 @@ Note that the name of the client settings context is the username for the client
10811081
| acl | String | A Named ACL to apply to the client. | |
10821082
| setvar | String | A channel variable key/value pair (using the nomenclature VARIABLE=value) that will be set on all channels originated from this client | |
10831083
| eventfilter | RegEx | This option may be present multiple times. This options allows clients to whitelist or blacklist events. A filter is assumed to be a whitelist unless preceeded by a '\!'.Evaluation of the filters is as follows:
1084-
* If no filters are configured all events are reported as normal.
1085-
* If there are white filters only: implied black all filter processed first, then white filters.
1086-
* If there are black filters only: implied white all filter processed first, then black filters.
1087-
* If there are both white and black filters: implied black all filter processed first, then white filters, and lastly black filters.
1088-
| |
1084+
| eventfilter | Structured Expression or RegEx (deprecated) | This option may be present multiple times. This option allows clients to whitelist or blacklist events. See [ami-event-filtering](ami-event-filtering.md) for details. **Added in:** Structured Expression syntax added in 18.25.0, 20.10.0, 21.5.0, 22.0.0 (October 2024) | |
10891085
| read | String | A comma delineated list of the allowed class authorizations applied to events | all |
10901086
| write | String | A comma delineated list of the allowed class authorizations applied to actions | all |
10911087

‎docs/Configuration/Interfaces/Asterisk-Manager-Interface-AMI/ami-event-filtering.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# AMI Event Filtering
2+
3+
## Overview
4+
5+
Event filtering allows AMI users to selectively include or exclude events based on event names, headers, and content. This feature helps reduce bandwidth and processing overhead by limiting events to only those relevant to your application.
6+
7+
There are two filtering methods available:
8+
- **Legacy Event Filtering** - Original regex-based method (maintained for backward compatibility)
9+
- **Advanced Event Filtering** - Recommended method with improved performance and flexibility
10+
11+
## Advanced Event Filtering (Recommended)
12+
13+
Advanced filtering provides efficient event selection using event name hashing and targeted header matching, avoiding the performance overhead of full-payload regex scanning.
14+
15+
### Syntax
16+
17+
```
18+
eventfilter(<match_criteria>) = [<match_expression>]
19+
```
20+
21+
### Match Criteria
22+
23+
You can specify up to one of each criterion in any order, separated by commas:
24+
25+
#### action(include|exclude)
26+
- **Default**: `include`
27+
- Controls whether matching events are included or excluded
28+
- `action(include)` - Include events that match
29+
- `action(exclude)` - Exclude events that match
30+
31+
#### name(<event_name>)
32+
- Matches events with the exact event name specified
33+
- Uses efficient hash-based matching instead of regex
34+
- Example: `name(Newchannel)`, `name(Hangup)`
35+
36+
#### header(<header_name>)
37+
- Only processes events containing the specified header
38+
- Constrains the match expression to search only that header's value
39+
- Example: `header(Channel)`, `header(Uniqueid)`
40+
41+
#### method(regex|exact|starts_with|ends_with|contains|none)
42+
- **Default**: `none`
43+
- Defines how the match expression is applied to event data
44+
45+
| Method | Description |
46+
|--------|-------------|
47+
| `regex` | Match as a regular expression anywhere in the data |
48+
| `exact` | Match the entire data exactly |
49+
| `starts_with` | Match at the beginning of the data |
50+
| `ends_with` | Match at the end of the data |
51+
| `contains` | Match anywhere in the data as a literal string |
52+
| `none` | Ignore match expression (useful for name-only filtering) |
53+
54+
### Filter Processing Order
55+
56+
1. **No filters configured** - All events are reported
57+
2. **Include filters only** - Events matching ANY include filter are reported
58+
3. **Exclude filters only** - Events matching ANY exclude filter are blocked
59+
4. **Both include and exclude** - Include filters are applied first, then exclude filters are applied to the resulting set
60+
61+
### Examples
62+
63+
#### Example 1: Include Only Newchannel Events
64+
65+
```ini
66+
eventfilter(name(Newchannel)) =
67+
```
68+
69+
/// warning | Empty Match Expression
70+
The empty right side (after the =) is intentional - you only care about the event name, not the payload content.
71+
///
72+
73+
#### Example 2: Exclude Local Channels from Newchannel and Hangup Events
74+
75+
```ini
76+
eventfilter(action(include),name(Newchannel)) =
77+
eventfilter(action(include),name(Hangup)) =
78+
eventfilter(action(exclude),header(Channel),method(starts_with)) = Local/
79+
```
80+
81+
This configuration:
82+
1. Includes all Newchannel events
83+
2. Includes all Hangup events
84+
3. Excludes any event with a Channel header starting with "Local/"
85+
86+
#### Example 3: Include Only Specific SIP Channels
87+
88+
```ini
89+
eventfilter(header(Channel),method(regex)) = (PJ)?SIP/(james|jim|john)-
90+
```
91+
92+
Matches events with a Channel header containing PJSIP or SIP channels for specific users.
93+
94+
#### Example 4: Exclude DAHDI Channels from All Events
95+
96+
```ini
97+
eventfilter(action(exclude),header(Channel),method(starts_with)) = DAHDI/
98+
```
99+
100+
Filters out any event where the Channel header starts with "DAHDI/".
101+
102+
#### Example 5: Multiple Event Type Filtering
103+
104+
```ini
105+
eventfilter(action(exclude),name(Newchannel),header(Channel),method(starts_with)) = Local/
106+
eventfilter(action(exclude),name(Hangup),header(Channel),method(starts_with)) = Local/
107+
```
108+
109+
Excludes Newchannel and Hangup events for Local channels, while allowing all other events and all other Newchannel/Hangup events.
110+
111+
## Legacy Event Filtering
112+
113+
/// warning | Deprecated
114+
Legacy filtering is maintained for backward compatibility but is not recommended for new implementations due to performance overhead.
115+
///
116+
117+
### How It Works
118+
119+
Legacy filters use regular expressions applied to the entire event payload. An exclamation point (!) prefix excludes matching events instead of including them.
120+
121+
### Limitations
122+
123+
- **Performance**: Regex matching runs against the full payload of every event
124+
- **Whitespace sensitivity**: Exact spacing and formatting must match
125+
- **Less readable**: Complex filters become difficult to maintain
126+
127+
### Examples
128+
129+
```ini
130+
# Include only Newchannel events
131+
eventfilter=Event: Newchannel
132+
133+
# Include Newchannel events with PJSIP channels
134+
eventfilter = Event: Newchannel.*Channel: PJSIP/
135+
136+
# Exclude events with DAHDI channels
137+
eventfilter=!Channel: DAHDI/
138+
```
139+
140+
## Best Practices
141+
142+
1. **Use Advanced Filtering** - It's significantly more efficient than legacy filtering
143+
2. **Order your criteria logically** - While order doesn't affect Asterisk, using `action, name, header, method` improves readability
144+
3. **Start with event names** - Use `name()` to filter by event type first for best performance
145+
4. **Use appropriate match methods** - Avoid `regex` when `starts_with`, `ends_with`, or `contains` will work
146+
5. **Test your filters** - Verify filters work as expected before deploying to production
147+
6. **Document your filters** - Add comments explaining complex filter logic
148+
149+
## Configuration Location
150+
151+
Event filters are configured in the AMI user configuration file:
152+
- **File**: `/etc/asterisk/manager.conf`
153+
- **Section**: Under each AMI user definition
154+
155+
Example configuration:
156+
157+
```ini
158+
[myamiuser]
159+
secret = mysecret
160+
read = system,call,log,verbose,command,agent,user
161+
write = system,call,log,verbose,command,agent,user
162+
eventfilter(action(include),name(Newchannel)) =
163+
eventfilter(action(include),name(Hangup)) =
164+
eventfilter(action(exclude),header(Channel),method(starts_with)) = Local/
165+
```
166+
167+
## See Also
168+
169+
- [Asterisk Manager Interface (AMI)](/Configuration/Interfaces/Asterisk-Manager-Interface-AMI/)
170+
- [AMI Configuration](/Configuration/Interfaces/Asterisk-Manager-Interface-AMI/AMI-Configuration/)
171+
- [AMI Events](/Configuration/Interfaces/Asterisk-Manager-Interface-AMI/AMI-Events/)

0 commit comments

Comments
 (0)