Skip to content

Commit a436a69

Browse files
jcolpphoneben
jcolp
authored and
phoneben
committed
AstriDevCon: Update for next virtual event.
1 parent 439f2bc commit a436a69

File tree

2 files changed

+176
-1
lines changed

2 files changed

+176
-1
lines changed

‎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/)

‎docs/Development/Roadmap/AstriDevCon.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,17 @@ Sangoma invites developers who are interested in the future of Asterisk to join
1212

1313
AstriDevCon is a mix of open and focused discussion all on topics within the realm of Asterisk development, primarily regarding current concerns that Asterisk faces and how to improve Asterisk for the future.
1414

15+
**Starting at [10AM EST](https://www.timeanddate.com/worldclock/fixedtime.html?msg=AstriDevCon+2025+November&iso=20251119T10&p1=250&ah=2).**
16+
17+
**Event ends at 12PM.**
18+
1519
### Agenda
1620

1721
If people have specific things they would like to bring up we will build a rough agenda, but otherwise the event is informal and people are welcome to bring up topics as things progress.
1822

1923
### Location
2024

21-
AstriDevCon is typically held virtually via [Sangoma Meet](https://meet.sangoma.com/AstriDevCon).
25+
AstriDevCon will be held virtually on November 19th on [Sangoma Meet](https://meet.sangoma.com/AstriDevCon).
2226

2327
Registering for AstriDevCon
2428
---------------------------

0 commit comments

Comments
 (0)