2 * Copyright (c) 2015 Cisco and/or its affiliates.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at:
7 * http://www.apache.org/licenses/LICENSE-2.0
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
16 * trace.c: VLIB trace buffer.
18 * Copyright (c) 2008 Eliot Dresselhaus
20 * Permission is hereby granted, free of charge, to any person obtaining
21 * a copy of this software and associated documentation files (the
22 * "Software"), to deal in the Software without restriction, including
23 * without limitation the rights to use, copy, modify, merge, publish,
24 * distribute, sublicense, and/or sell copies of the Software, and to
25 * permit persons to whom the Software is furnished to do so, subject to
26 * the following conditions:
28 * The above copyright notice and this permission notice shall be
29 * included in all copies or substantial portions of the Software.
31 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
32 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
33 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
34 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
35 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
36 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
37 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
40 #include <vlib/vlib.h>
41 #include <vlib/threads.h>
43 /* Helper function for nodes which only trace buffer data. */
45 vlib_trace_frame_buffers_only (vlib_main_t * vm,
46 vlib_node_runtime_t * node,
49 uword next_buffer_stride,
50 uword n_buffer_data_bytes_in_trace)
60 vlib_buffer_t * b0, * b1;
63 /* Prefetch next iteration. */
64 vlib_prefetch_buffer_with_index (vm, from[2], LOAD);
65 vlib_prefetch_buffer_with_index (vm, from[3], LOAD);
70 b0 = vlib_get_buffer (vm, bi0);
71 b1 = vlib_get_buffer (vm, bi1);
73 if (b0->flags & VLIB_BUFFER_IS_TRACED)
75 t0 = vlib_add_trace (vm, node, b0, n_buffer_data_bytes_in_trace);
76 memcpy (t0, b0->data + b0->current_data,
77 n_buffer_data_bytes_in_trace);
79 if (b1->flags & VLIB_BUFFER_IS_TRACED)
81 t1 = vlib_add_trace (vm, node, b1, n_buffer_data_bytes_in_trace);
82 memcpy (t1, b1->data + b1->current_data,
83 n_buffer_data_bytes_in_trace);
97 b0 = vlib_get_buffer (vm, bi0);
99 if (b0->flags & VLIB_BUFFER_IS_TRACED)
101 t0 = vlib_add_trace (vm, node, b0, n_buffer_data_bytes_in_trace);
102 memcpy (t0, b0->data + b0->current_data,
103 n_buffer_data_bytes_in_trace);
110 /* Free up all trace buffer memory. */
112 clear_trace_buffer (void)
115 vlib_trace_main_t * tm;
121 tm = &this_vlib_main->trace_main;
122 mainheap = clib_mem_set_heap (this_vlib_main->heap_base);
124 tm->trace_active_hint = 0;
126 for (i = 0; i < vec_len (tm->trace_buffer_pool); i++)
127 if (! pool_is_free_index (tm->trace_buffer_pool, i))
128 vec_free (tm->trace_buffer_pool[i]);
129 pool_free (tm->trace_buffer_pool);
130 clib_mem_set_heap (mainheap);
134 static u8 * format_vlib_trace (u8 * s, va_list * va)
136 vlib_main_t * vm = va_arg (*va, vlib_main_t *);
137 vlib_trace_header_t * h = va_arg (*va, vlib_trace_header_t *);
138 vlib_trace_header_t * e = vec_end (h);
139 vlib_node_t * node, * prev_node;
140 clib_time_t * ct = &vm->clib_time;
146 node = vlib_get_node (vm, h->node_index);
148 if (node != prev_node)
150 t = (h->time - vm->cpu_time_main_loop_start) * ct->seconds_per_clock;
151 s = format (s, "\n%U: %v",
152 format_time_interval, "h:m:s:u", t,
157 if (node->format_trace)
158 s = format (s, "\n %U",
159 node->format_trace, vm, node, h->data);
161 s = format (s, "\n %U",
162 node->format_buffer, h->data);
164 h = vlib_trace_header_next (h);
170 /* Root of all trace cli commands. */
171 VLIB_CLI_COMMAND (trace_cli_command,static) = {
173 .short_help = "Packet tracer commands",
177 trace_cmp (void * a1, void * a2)
179 vlib_trace_header_t ** t1 = a1;
180 vlib_trace_header_t ** t2 = a2;
181 i64 dt = t1[0]->time - t2[0]->time;
182 return dt < 0 ? -1 : (dt > 0 ? +1 : 0);
186 * Return 1 if this packet passes the trace filter, or 0 otherwise
188 u32 filter_accept (vlib_trace_main_t * tm, vlib_trace_header_t * h)
190 vlib_trace_header_t * e = vec_end (h);
192 if (tm->filter_flag == 0) return 1;
194 if (tm->filter_flag == FILTER_FLAG_INCLUDE)
198 if (h->node_index == tm->filter_node_index)
200 h = vlib_trace_header_next (h);
204 else /* FILTER_FLAG_EXCLUDE */
208 if (h->node_index == tm->filter_node_index)
210 h = vlib_trace_header_next (h);
219 * Remove traces from the trace buffer pool that don't pass the filter
221 void trace_apply_filter (vlib_main_t * vm)
223 vlib_trace_main_t * tm = &vm->trace_main;
224 vlib_trace_header_t ** h;
225 vlib_trace_header_t *** traces_to_remove = 0;
232 if (tm->filter_flag == FILTER_FLAG_NONE)
236 * Ideally we would retain the first N traces that pass the filter instead
240 pool_foreach (h, tm->trace_buffer_pool,
242 accept = filter_accept(tm, h[0]);
244 if ((n_accepted == tm->filter_count) || !accept)
245 vec_add1 (traces_to_remove, h);
250 /* remove all traces that we don't want to keep */
251 for (index=0; index<vec_len(traces_to_remove); index++)
253 trace_index = traces_to_remove[index] - tm->trace_buffer_pool;
254 _vec_len (tm->trace_buffer_pool[trace_index]) = 0;
255 pool_put_index (tm->trace_buffer_pool, trace_index);
258 vec_free (traces_to_remove);
261 static clib_error_t *
262 cli_show_trace_buffer (vlib_main_t * vm,
263 unformat_input_t * input,
264 vlib_cli_command_t * cmd)
266 vlib_trace_main_t * tm;
267 vlib_trace_header_t ** h, ** traces;
274 * By default display only this many traces. To display more, explicitly
275 * specify a max. This prevents unexpectedly huge outputs.
278 while (unformat_check_input(input) != (uword)UNFORMAT_END_OF_INPUT)
280 if (unformat (input, "max %d", &max))
283 return clib_error_create ("expected 'max COUNT', got `%U'",
284 format_unformat_error, input);
288 /* Get active traces from pool. */
294 fmt = "------------------- Start of thread %d %s -------------------\n";
295 s = format (s, fmt, index, vlib_worker_threads[index].name);
297 tm = &this_vlib_main->trace_main;
299 mainheap = clib_mem_set_heap (this_vlib_main->heap_base);
301 trace_apply_filter(this_vlib_main);
304 pool_foreach (h, tm->trace_buffer_pool,
306 vec_add1 (traces, h[0]);
309 if (vec_len (traces) == 0)
311 clib_mem_set_heap (mainheap);
312 s = format (s, "No packets in trace buffer\n");
316 /* Sort them by increasing time. */
317 vec_sort_with_function (traces, trace_cmp);
319 for (i = 0; i < vec_len (traces); i++)
323 vlib_cli_output (vm, "Limiting display to %d packets."
324 " To display more specify max.", max);
328 clib_mem_set_heap (mainheap);
330 s = format (s, "Packet %d\n%U\n\n", i + 1,
331 format_vlib_trace, vm, traces[i]);
333 mainheap = clib_mem_set_heap (this_vlib_main->heap_base);
338 clib_mem_set_heap (mainheap);
343 vlib_cli_output (vm, (char *) s);
348 VLIB_CLI_COMMAND (show_trace_cli,static) = {
349 .path = "show trace",
350 .short_help = "Show trace buffer [max COUNT]",
351 .function = cli_show_trace_buffer,
354 static clib_error_t *
355 cli_add_trace_buffer (vlib_main_t * vm,
356 unformat_input_t * input,
357 vlib_cli_command_t * cmd)
359 vlib_trace_main_t * tm;
360 vlib_trace_node_t * tn;
363 if (unformat (input, "%U %d", unformat_vlib_node, vm, &node_index, &add))
366 return clib_error_create ("expected NODE COUNT, got `%U'",
367 format_unformat_error, input);
372 tm = &this_vlib_main->trace_main;
374 tm->trace_active_hint = 1;
376 oldheap = clib_mem_set_heap (this_vlib_main->heap_base);
378 vec_validate (tm->nodes, node_index);
379 tn = tm->nodes + node_index;
381 clib_mem_set_heap (oldheap);
387 VLIB_CLI_COMMAND (add_trace_cli,static) = {
389 .short_help = "Trace given number of packets",
390 .function = cli_add_trace_buffer,
395 * Configure a filter for packet traces.
397 * This supplements the packet trace feature so that only packets matching
398 * the filter are included in the trace. Currently the only filter is to
399 * keep packets that include a certain node in the trace or exclude a certain
402 * The count of traced packets in the "trace add" command is still used to
403 * create a certain number of traces. The "trace filter" command specifies
404 * how many of those packets should be retained in the trace.
406 * For example, 1Mpps of traffic is arriving and one of those packets is being
407 * dropped. To capture the trace for only that dropped packet, you can do:
408 * trace filter include error-drop 1
409 * trace add dpdk-input 1000000
413 * Note that the filter could be implemented by capturing all traces and just
414 * reducing traces displayed by the "show trace" function. But that would
415 * require a lot of memory for storing the traces, making that infeasible.
417 * To remove traces from the trace pool that do not include a certain node
418 * requires that the trace be "complete" before applying the filter. To
419 * accomplish this, the trace pool is filtered upon each iteraction of the
420 * main vlib loop. Doing so keeps the number of allocated traces down to a
421 * reasonably low number. This requires that tracing for a buffer is not
422 * performed after the vlib main loop interation completes. i.e. you can't
423 * save away a buffer temporarily then inject it back into the graph and
424 * expect that the trace_index is still valid (such as a traffic manager might
425 * do). A new trace buffer should be allocated for those types of packets.
427 * The filter can be extended to support multiple nodes and other match
428 * criteria (e.g. input sw_if_index, mac address) but for now just checks if
429 * a specified node is in the trace or not in the trace.
431 static clib_error_t *
432 cli_filter_trace (vlib_main_t * vm,
433 unformat_input_t * input,
434 vlib_cli_command_t * cmd)
436 vlib_trace_main_t * tm = &vm->trace_main;
437 u32 filter_node_index;
442 if (unformat (input, "include %U %d",
443 unformat_vlib_node, vm, &filter_node_index, &filter_count))
445 filter_flag = FILTER_FLAG_INCLUDE;
447 else if (unformat (input, "exclude %U %d",
448 unformat_vlib_node, vm, &filter_node_index, &filter_count))
450 filter_flag = FILTER_FLAG_EXCLUDE;
452 else if (unformat (input, "none"))
454 filter_flag = FILTER_FLAG_NONE;
455 filter_node_index = 0;
459 return clib_error_create ("expected 'include NODE COUNT' or 'exclude NODE COUNT' or 'none', got `%U'",
460 format_unformat_error, input);
464 tm = &this_vlib_main->trace_main;
465 tm->filter_node_index = filter_node_index;
466 tm->filter_flag = filter_flag;
467 tm->filter_count = filter_count;
470 * Clear the trace limits to stop any in-progress tracing
471 * Prevents runaway trace allocations when the filter changes (or is removed)
473 mainheap = clib_mem_set_heap (this_vlib_main->heap_base);
474 vec_free (tm->nodes);
475 clib_mem_set_heap (mainheap);
481 VLIB_CLI_COMMAND (filter_trace_cli,static) = {
482 .path = "trace filter",
483 .short_help = "filter trace output - include NODE COUNT | exclude NODE COUNT | none",
484 .function = cli_filter_trace,
487 static clib_error_t *
488 cli_clear_trace_buffer (vlib_main_t * vm,
489 unformat_input_t * input,
490 vlib_cli_command_t * cmd)
492 clear_trace_buffer ();
496 VLIB_CLI_COMMAND (clear_trace_cli,static) = {
497 .path = "clear trace",
498 .short_help = "Clear trace buffer and free memory",
499 .function = cli_clear_trace_buffer,
502 /* Dummy function to get us linked in. */
503 void vlib_trace_cli_reference (void) {}