StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
telemetry.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-Multimedia.
5 *
6 * StormByte-Multimedia original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-Multimedia source in this
20 * file. Third-party components — including FFmpeg and embedded trained data —
21 * remain under their own licenses and are not covered by the commercial grant.
22 *
23 * A written StormByte commercial agreement may license this original source
24 * on terms other than the LGPL, including specific use, distribution or
25 * linking arrangements such as static linking, as stated in that agreement.
26 * It does not grant rights to dependencies or waive their license conditions.
27 * Enabling WITH_GPL or WITH_NONFREE may include components with separate
28 * obligations for modification, linking (static or dynamic), redistribution
29 * or works that incorporate them. The person modifying, linking, packaging or
30 * distributing the resulting work is responsible for determining and meeting
31 * all applicable requirements, including any needed patent permissions.
32 * A StormByte commercial agreement does not provide those rights for GPL or
33 * nonfree components.
34 *
35 * Neither license grants any patent rights. Any patent licenses required
36 * to use this software or third-party components must be obtained separately
37 * from the patent holders.
38 *
39 * StormByte-Multimedia is distributed in the hope that it will be useful,
40 * but WITHOUT ANY WARRANTY; without even the implied warranty of
41 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
42 * GNU Lesser General Public License for more details.
43 *
44 * You should have received a copy of the GNU Lesser General Public License
45 * version 3 along with StormByte-Multimedia. If not, see
46 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
47 *
48 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
49 */
50
51#pragma once
52
53#include <StormByte/buffer/byte_budget.hxx>
58#include <StormByte/safe/atomic.hxx>
59#include <StormByte/safe/mutex.hxx>
60#include <StormByte/safe/optional.hxx>
61#include <StormByte/safe/pointers.hxx>
62#include <StormByte/safe/string.hxx>
63#include <StormByte/safe/vector.hxx>
64#include <StormByte/telemetry.hxx>
65
66#include <chrono>
67#include <cstdint>
68#include <string_view>
69
78 class Topology;
79
83 class Transcoder;
84}
85
90namespace StormByte {
95 namespace Multimedia {
102 namespace Pipeline {
133 public:
138
142 ~StageTelemetry() noexcept override;
143
149
155
163
168 void SetOrigin(std::string_view origin) const;
169
175
180 void RecordInput(Kind kind) noexcept;
181
186 void RecordOutput(Kind kind) noexcept;
187
192 void RecordProcess(std::chrono::nanoseconds duration) noexcept;
193
198 void RecordWait(std::chrono::nanoseconds duration) noexcept;
199
204 void RecordSetup(std::chrono::nanoseconds duration) noexcept;
205
210 void SetState(State state) noexcept;
211
217
221 void Start() noexcept;
222
226 void Finish() noexcept;
227
232 std::uint64_t ProcessCalls() const noexcept;
233
238 std::uint64_t InputFrames() const noexcept;
239
244 std::uint64_t InputPackets() const noexcept;
245
250 std::uint64_t OutputFrames() const noexcept;
251
256 std::uint64_t OutputPackets() const noexcept;
257
262 std::chrono::nanoseconds ProcessTotal() const noexcept;
263
268 std::chrono::nanoseconds ProcessMean() const noexcept;
269
274 std::chrono::nanoseconds ProcessMinimum() const noexcept;
275
280 std::chrono::nanoseconds ProcessMaximum() const noexcept;
281
286 std::uint64_t WaitCount() const noexcept;
287
292 std::chrono::nanoseconds WaitTotal() const noexcept;
293
298 std::chrono::nanoseconds WaitMaximum() const noexcept;
299
304 std::chrono::nanoseconds SetupTime() const noexcept;
305
310 std::chrono::nanoseconds Elapsed() const noexcept;
311
316 State Status() const noexcept;
317
322 StormByte::Safe::Optional<StormByte::Safe::String> Error() const;
323
328 operator StormByte::Safe::String() const override;
329
330 private:
331 WorkerActivity m_activity;
332 mutable StormByte::Safe::Mutex m_activity_lock;
333 StormByte::Safe::Vector<StormByte::Safe::Shared<WorkerActivity>> m_activity_workers;
334 bool m_activity_complete = true;
335 StormByte::Safe::Atomic<std::uint64_t> m_process_calls;
336
337 StormByte::Safe::Atomic<std::uint64_t> m_input_frames;
338
339 StormByte::Safe::Atomic<std::uint64_t> m_input_packets;
340
341 StormByte::Safe::Atomic<std::uint64_t> m_output_frames;
342
343 StormByte::Safe::Atomic<std::uint64_t> m_output_packets;
344
345 StormByte::Safe::Atomic<std::int64_t> m_process_total_ns;
346
347 StormByte::Safe::Atomic<std::int64_t> m_process_min_ns;
348
349 StormByte::Safe::Atomic<std::int64_t> m_process_max_ns;
350
351 StormByte::Safe::Atomic<std::uint64_t> m_wait_count;
352
353 StormByte::Safe::Atomic<std::int64_t> m_wait_total_ns;
354
355 StormByte::Safe::Atomic<std::int64_t> m_wait_max_ns;
356
357 StormByte::Safe::Atomic<std::int64_t> m_setup_ns;
358
359 StormByte::Safe::Atomic<std::int64_t> m_started_ns;
360
361 StormByte::Safe::Atomic<std::int64_t> m_finished_ns;
362
363 StormByte::Safe::Atomic<int> m_state;
364
365 mutable StormByte::Safe::Mutex m_error_lock;
366
367 StormByte::Safe::Optional<StormByte::Safe::String> m_error;
368
369 mutable StormByte::Safe::Mutex m_origin_lock;
370
371 mutable StormByte::Safe::String m_origin;
372 };
373
387
401
413
423
432
442
451
452 }
453 }
454}
455
457
458namespace StormByte {
459 namespace Multimedia {
460 namespace Pipeline {
485
508
523
524 }
525 }
526}
527
531
532namespace StormByte {
533 namespace Multimedia {
534 namespace Pipeline {
555 }
556 }
557}
558
562
567namespace StormByte {
572 namespace Multimedia {
579 namespace Pipeline {
603 public:
608
614
618 ~JobTelemetry() noexcept override;
619
626 StormByte::Safe::Shared<const StageTelemetry> metrics);
627
632 StormByte::Safe::Vector<Stage> Stages() const;
633
652
658 void SampleMemory() noexcept;
659
664 StormByte::Safe::Optional<std::uint64_t> MemoryCurrent() const;
665
670 StormByte::Safe::Optional<std::uint64_t> MemoryMinimum() const;
671
676 StormByte::Safe::Optional<std::uint64_t> MemoryMaximum() const;
677
682 StormByte::Safe::Optional<std::uint64_t> PeakMemory() const;
683
688 std::uint64_t MemorySamples() const noexcept;
689
694 operator StormByte::Safe::String() const override;
695
696 private:
698
707 StormByte::Safe::Shared<StormByte::Multimedia::Backend::Pipeline::Topology> TopologyRecorder() noexcept;
708
709 mutable StormByte::Safe::Mutex m_stages_lock;
710
711 StormByte::Safe::Shared<StormByte::Multimedia::Backend::Pipeline::Topology> m_topology;
712
713 StormByte::Safe::Atomic<bool> m_topology_failed;
714
715 StormByte::Safe::Vector<Stage> m_stages;
716
717 StormByte::Safe::Atomic<std::uint64_t> m_memory_current;
718
719 StormByte::Safe::Atomic<std::uint64_t> m_memory_min;
720
721 StormByte::Safe::Atomic<std::uint64_t> m_memory_max;
722
723 StormByte::Safe::Atomic<std::uint64_t> m_memory_samples;
724 };
725 }
726 }
727}
728
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
Decodes packets of one origin track into frames.
Definition decoder.hxx:148
Reads interleaved compressed packets from the Plan reader.
Definition demuxer.hxx:148
Encodes frames of one output track into packets.
Definition encoder.hxx:145
void SampleMemory() noexcept
Sample current process resident memory.
JobTelemetry()
Construct empty job telemetry.
StormByte::Safe::Optional< std::uint64_t > PeakMemory() const
Alias for the maximum sampled resident-memory value.
TopologySnapshot Topology() const
Snapshot the real stages, queues and shared budgets of the job.
friend class StormByte::Multimedia::Backend::Pipeline::Transcoder
Definition telemetry.hxx:697
void RegisterStage(StormByte::Safe::String name, StormByte::Safe::Shared< const StageTelemetry > metrics)
Add a stage handle once.
StormByte::Safe::Optional< std::uint64_t > MemoryMaximum() const
Highest process resident memory sample.
StormByte::Safe::Vector< Stage > Stages() const
Snapshot registered stages in registration order.
~JobTelemetry() noexcept override
Release job telemetry in its providing library.
TelemetryStage Stage
Named stage telemetry retained past worker teardown.
Definition telemetry.hxx:607
StormByte::Safe::Optional< std::uint64_t > MemoryMinimum() const
Lowest process resident memory sample.
std::uint64_t MemorySamples() const noexcept
Number of successful resident-memory samples.
StormByte::Safe::Optional< std::uint64_t > MemoryCurrent() const
Current process resident bytes at the last sample.
operator StormByte::Safe::String() const override
Flatten memory and stage counters into an owned Safe::String.
Writes interleaved packets to the Plan writer.
Definition muxer.hxx:217
One compressed access unit.
Definition packet.hxx:102
Forwards compressed packets of one origin track to the muxer.
Definition remuxer.hxx:133
Thread-safe counters and timings for one pipeline worker.
Definition telemetry.hxx:132
std::chrono::nanoseconds ProcessTotal() const noexcept
Sum of Process call durations.
StormByte::Safe::Shared< WorkerActivity > RegisterActivityWorker(ActivityRole role, int track) noexcept
Register another execution domain without affecting the job on allocation failure.
void SetError(StormByte::Safe::String reason)
Store a stage failure reason.
std::chrono::nanoseconds ProcessMaximum() const noexcept
Maximum Process call duration.
std::chrono::nanoseconds WaitMaximum() const noexcept
Maximum blocking wait duration.
std::chrono::nanoseconds SetupTime() const noexcept
Worker setup duration.
std::uint64_t OutputPackets() const noexcept
Number of emitted packets.
std::chrono::nanoseconds ProcessMean() const noexcept
Mean Process call duration.
StageActivitySnapshot Activity() const
Read independent worker activity, including open intervals.
State Status() const noexcept
Latest worker lifecycle state.
std::chrono::nanoseconds WaitTotal() const noexcept
Sum of blocking wait durations.
void Start() noexcept
Mark the start of stage setup.
std::uint64_t InputPackets() const noexcept
Number of consumed packets.
StormByte::Safe::Optional< StormByte::Safe::String > Error() const
Failure text, if the stage failed.
std::chrono::nanoseconds Elapsed() const noexcept
Total elapsed time since Start.
void Finish() noexcept
Mark the end of stage execution.
StageTelemetry()
Construct empty stage counters.
void RecordOutput(Kind kind) noexcept
Record one emitted unit.
void RecordProcess(std::chrono::nanoseconds duration) noexcept
Record one Process call duration.
operator StormByte::Safe::String() const override
Flatten all stage counters into an owned Safe::String.
std::uint64_t WaitCount() const noexcept
Number of blocking waits.
std::uint64_t OutputFrames() const noexcept
Number of emitted frames.
std::uint64_t ProcessCalls() const noexcept
Number of Process calls, including source ticks and flushes.
void SetState(State state) noexcept
Set the latest stage lifecycle state.
std::uint64_t InputFrames() const noexcept
Number of consumed frames.
WorkerActivity & MainActivity() noexcept
Access the main worker clock for producer instrumentation.
~StageTelemetry() noexcept override
Release stage telemetry in its providing library.
void RecordInput(Kind kind) noexcept
Record one consumed unit.
std::chrono::nanoseconds ProcessMinimum() const noexcept
Minimum Process call duration.
void SetOrigin(std::string_view origin) const
Set the stage origin label.
void RecordWait(std::chrono::nanoseconds duration) noexcept
Record one completed blocking wait.
StormByte::Safe::String Origin() const
Stage identity recorded by its owning object.
void RecordSetup(std::chrono::nanoseconds duration) noexcept
Record setup duration.
Provider-owned clock for one execution thread.
Definition activity.hxx:179
State
Lifecycle of the stage thread.
Definition typedefs.hxx:211
Kind
Whether an Item is a decoded frame or a compressed packet.
Definition typedefs.hxx:109
Multimedia module of the StormByte suite.
Pipeline Demux / decode / filter / encode / mux types.
Multimedia-owned pipeline stages and unit holders.
Frame and packet steps attached to a job or a raw pipeline.
Demux / decode / filter / encode / mux types.
TopologyFilterKind
Filter family of a TopologyStageKind::Filter stage.
Definition telemetry.hxx:406
@ None
Stage is not a filter.
Definition telemetry.hxx:407
@ Analytics
Observing analytics filter (Filter::Analytics and derived).
Definition telemetry.hxx:410
@ Process
Frame-processing filter (Filter::Process and derived).
Definition telemetry.hxx:408
TopologySnapshotState
Whether values are read live or are frozen copies.
Definition telemetry.hxx:437
@ Unfrozen
Snapshot only: the run was torn down but its final copy could not be allocated. Queues keep their own...
Definition telemetry.hxx:440
@ Live
Read from the running queue or budget when the snapshot was taken.
Definition telemetry.hxx:438
@ Final
Captured when the owning stage or job run was torn down; never changes again.
Definition telemetry.hxx:439
TopologyQueueRole
Relation between a stage and one queue.
Definition telemetry.hxx:418
@ Output
The stage is a registered producer of this queue.
Definition telemetry.hxx:420
@ Pending
Stage-owned pending queue (demux park) before its output queues.
Definition telemetry.hxx:421
@ Input
The stage consumes this queue.
Definition telemetry.hxx:419
TopologyQueueKind
Storage that backs a TopologyQueue.
Definition telemetry.hxx:428
@ DemuxPending
Demuxer per-track pending list; elements only, no byte accounting.
Definition telemetry.hxx:430
@ Pipe
Buffer::Sink hopper owned by its consumer stage.
Definition telemetry.hxx:429
ActivityRole
Concurrent execution domains; codec-internal threads are not observed.
Definition activity.hxx:94
TopologyStageKind
Kind of real pipeline stage reported by JobTelemetry::Topology.
Definition telemetry.hxx:392
@ Demuxer
Container reader; owns the demux pending queues.
Definition telemetry.hxx:393
@ InspectionDecoder
Internal decoder created only to feed analytics filters.
Definition telemetry.hxx:399
Multimedia module of the StormByte suite.
@ Other
Any other FFmpeg type (dictionary, rational, size, ...).
Definition encoder_info.hxx:94
@ None
No flags.
Definition feature.hxx:83
Root namespace of the StormByte C++ suite.
STL namespace.
Activity coverage and independent workers of a stage.
Definition activity.hxx:159
Named stage telemetry retained past worker teardown.
Definition telemetry.hxx:382
StormByte::Safe::Shared< const StageTelemetry > Metrics
Shared stage counter handle retained across DLL boundaries.
Definition telemetry.hxx:385
StormByte::Safe::String Name
Display name, including track scope when applicable.
Definition telemetry.hxx:383
Shared byte budget reported once for every queue that charges it.
Definition telemetry.hxx:516
StormByte::Safe::Vector< std::uint64_t > Queues
Queue ids charging this budget in this snapshot.
Definition telemetry.hxx:520
std::uint64_t Id
Stable entry id; equal ids mean the same shared budget.
Definition telemetry.hxx:517
StormByte::Buffer::BudgetSnapshot Snapshot
Aggregate reservation counters.
Definition telemetry.hxx:521
bool Identified
True for valid handles, including closed budgets.
Definition telemetry.hxx:519
TopologySnapshotState State
Live or final reading.
Definition telemetry.hxx:518
Stage-to-queue link in a topology snapshot.
Definition telemetry.hxx:447
std::uint64_t Queue
TopologyQueue::Id.
Definition telemetry.hxx:448
TopologyQueueRole Role
Stage relation to that queue.
Definition telemetry.hxx:449
One real queue and its Buffer accounting.
Definition telemetry.hxx:496
StormByte::Safe::Optional< std::uint64_t > Budget
TopologyBudget::Id charged by this queue, if any.
Definition telemetry.hxx:502
StormByte::Safe::Vector< std::uint64_t > Producers
Registered producer stage ids.
Definition telemetry.hxx:501
StormByte::Safe::Optional< enum StormByte::Multimedia::Type > Media
Media carried, when known.
Definition telemetry.hxx:505
std::uint64_t Id
Stable queue id, unique in the process.
Definition telemetry.hxx:497
StormByte::Safe::Optional< std::uint64_t > Consumer
Consumer stage id; for pending queues the owning demuxer.
Definition telemetry.hxx:500
int Key
Hopper key in the consumer (track index for pending queues).
Definition telemetry.hxx:499
TopologyQueueKind Kind
Backing storage.
Definition telemetry.hxx:498
TopologySnapshotState State
Live or final reading.
Definition telemetry.hxx:504
bool BytesAccounted
False when the queue never accounts bytes.
Definition telemetry.hxx:503
StormByte::Buffer::QueueSnapshot Snapshot
Limits, occupancy, peaks, pressure, waits, Closed and Exists.
Definition telemetry.hxx:506
Owned, coherent-per-queue view of the pipeline stages and queues.
Definition telemetry.hxx:545
bool RecorderFailed
The latest run could not allocate its topology recorder: nothing was recorded, Available is false and...
Definition telemetry.hxx:547
StormByte::Safe::Vector< TopologyBudget > Budgets
Unique budgets.
Definition telemetry.hxx:553
StormByte::Safe::Vector< TopologyQueue > Queues
Unique queues.
Definition telemetry.hxx:552
std::uint64_t Run
Run generation; increases on each registration reset.
Definition telemetry.hxx:550
bool Available
False before a run registered its topology.
Definition telemetry.hxx:546
bool Complete
False when telemetry bookkeeping could not allocate; stages, queues, producer links,...
Definition telemetry.hxx:548
StormByte::Safe::Vector< TopologyStage > Stages
Stages in pipeline order, then registration order.
Definition telemetry.hxx:551
TopologySnapshotState State
Final once the run tore its stages down.
Definition telemetry.hxx:549
Structured identity of one real pipeline stage.
Definition telemetry.hxx:469
StormByte::Safe::Optional< enum StormByte::Multimedia::Type > Media
Media handled; absent for multi-track stages.
Definition telemetry.hxx:475
StormByte::Safe::Optional< int > Track
Input (source) track index.
Definition telemetry.hxx:473
std::uint64_t Id
Stable stage id, unique in the process.
Definition telemetry.hxx:470
std::uint32_t Sequence
Registration order within the run.
Definition telemetry.hxx:480
StormByte::Safe::String Name
JobTelemetry::Stages name for the same counters; origin label for stages not listed there.
Definition telemetry.hxx:478
StormByte::Safe::Vector< TopologyQueueRef > Queues
Inputs, outputs and pending queues of this stage.
Definition telemetry.hxx:483
StormByte::Safe::Optional< int > OutputTrack
Output (muxer) track index.
Definition telemetry.hxx:474
StormByte::Safe::String FilterName
Filter constructor name; empty when not a filter.
Definition telemetry.hxx:477
StormByte::Safe::Shared< const StageTelemetry > Metrics
Shared stage counters.
Definition telemetry.hxx:481
StageActivitySnapshot Activity
Independent worker samples, frozen by value in a final topology.
Definition telemetry.hxx:482
TopologyFilterKind Filter
Filter family; None unless Kind is Filter.
Definition telemetry.hxx:472
TopologyStageKind Kind
Stage kind.
Definition telemetry.hxx:471
std::uint32_t Order
Longest producer hop count from a source stage.
Definition telemetry.hxx:479
StormByte::Safe::Optional< std::uint32_t > FilterPosition
Zero-based position in the track filter list.
Definition telemetry.hxx:476
#define STORMBYTE_MULTIMEDIA_PUBLIC
Definition visibility.h:61