PcapFileEx.Stats (pcap_file_ex v0.5.5)

@type stats() :: %{
  packet_count: non_neg_integer(),
  total_bytes: non_neg_integer(),
  min_packet_size: non_neg_integer() | nil,
  max_packet_size: non_neg_integer(),
  avg_packet_size: float(),
  first_timestamp: DateTime.t() | nil,
  last_timestamp: DateTime.t() | nil,
  duration_seconds: float() | nil
}

Functions

compute(path)

@spec compute(Path.t()) :: {:ok, stats()} | {:error, String.t()}

Computes statistics for a capture file.

Reads all packets and computes various statistics about the capture.

Note: This function loads all packets into memory. For large files, consider using compute_streaming/1 instead.

Examples

{:ok, stats} = PcapFileEx.Stats.compute("capture.pcap")
IO.inspect(stats.packet_count)
IO.inspect(stats.total_bytes)

compute_from_packets(packets)

@spec compute_from_packets([PcapFileEx.Packet.t()]) :: stats()

Computes statistics from a list of packets.

Examples

{:ok, packets} = PcapFileEx.read_all("capture.pcap")
stats = PcapFileEx.Stats.compute_from_packets(packets)

compute_streaming(path)

@spec compute_streaming(Path.t() | Enumerable.t()) :: {:ok, stats()} | stats()

Computes statistics for a capture file using streaming (constant memory).

Unlike compute/1, this function processes packets one at a time without loading the entire file into memory. This is ideal for large files (>100MB).

Accepts either a file path or an existing stream of packets.

Examples

# From file path
{:ok, stats} = PcapFileEx.Stats.compute_streaming("huge_10gb.pcap")
IO.inspect(stats.packet_count)

# From stream (can be combined with filtering)
stats =
  PcapFileEx.stream!("capture.pcap")
  |> PcapFileEx.Filter.by_protocol(:tcp)
  |> PcapFileEx.Stats.compute_streaming()

IO.inspect(stats.total_bytes)

duration(path)

@spec duration(Path.t()) :: {:ok, float()} | {:error, String.t()}

Gets the duration of a capture in seconds.

Examples

{:ok, duration} = PcapFileEx.Stats.duration("capture.pcap")
IO.puts("Capture duration: #{duration} seconds")

packet_count(path)

@spec packet_count(Path.t()) :: {:ok, non_neg_integer()} | {:error, String.t()}

Gets the packet count from a capture file.

This is optimized to just count packets without storing them in memory.

Examples

{:ok, count} = PcapFileEx.Stats.packet_count("capture.pcap")
IO.puts("Total packets: #{count}")

size_distribution(path)

@spec size_distribution(Path.t()) ::
  {:ok,
   %{
     min: non_neg_integer(),
     max: non_neg_integer(),
     median: float(),
     p95: float(),
     p99: float()
   }}
  | {:error, String.t()}

Computes packet size distribution statistics.

Returns a map with percentile information about packet sizes.

Examples

{:ok, dist} = PcapFileEx.Stats.size_distribution("capture.pcap")
IO.inspect(dist.median)
IO.inspect(dist.p95)

time_range(path)

@spec time_range(Path.t()) ::
  {:ok, {DateTime.t(), DateTime.t()}} | {:error, String.t()}

Gets the time range of packets in a capture file.

Returns the first and last packet timestamps.

Examples

{:ok, {first, last}} = PcapFileEx.Stats.time_range("capture.pcap")
IO.puts("Capture from #{first} to #{last}")

total_bytes(path)

@spec total_bytes(Path.t()) :: {:ok, non_neg_integer()} | {:error, String.t()}

Gets the total bytes captured in a file.

Examples

{:ok, bytes} = PcapFileEx.Stats.total_bytes("capture.pcap")
IO.puts("Total bytes: #{bytes}")