1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9#pragma once
10
11#include <memory>
12#include <set>
13#include <thread>
14#include <vector>
15
16#include "ActivityType.h"
17#include "ActivityTraceInterface.h"
18#include "IActivityProfiler.h"
19
20namespace libkineto {
21
22class ActivityProfilerController;
23struct CpuTraceBuffer;
24class Config;
25
26class ActivityProfilerInterface {
27
28 public:
29 virtual ~ActivityProfilerInterface() {};
30
31 virtual void init() {}
32 virtual bool isInitialized() {
33 return false;
34 }
35 virtual bool isActive(){
36 return false;
37 }
38
39 // *** Asynchronous API ***
40 // Instead of starting and stopping the trace manually, provide a start time
41 // and duration and / or iteration stop criterion.
42 // Tracing terminates when either condition is met.
43 virtual void scheduleTrace(const std::string& configStr) {}
44
45 // *** Synchronous API ***
46 // These must be called in order:
47 // prepareTrace -> startTrace -> stopTrace.
48
49 // Many tracing structures are lazily initialized during trace collection,
50 // with potentially high overhead.
51 // Call prepareTrace to enable tracing, then run the region to trace
52 // at least once (and ideally run the same code that is to be traced) to
53 // allow tracing structures to be initialized.
54 virtual void prepareTrace(
55 const std::set<ActivityType>& activityTypes,
56 const std::string& configStr = "") {}
57
58 // Start recording, potentially reusing any buffers allocated since
59 // prepareTrace was called.
60 virtual void startTrace() {}
61
62 // Stop and process trace, producing an in-memory list of trace records.
63 // The processing will be done synchronously (using the calling thread.)
64 virtual std::unique_ptr<ActivityTraceInterface> stopTrace() {
65 return nullptr;
66 }
67
68 // Re-evaluate internal state to allow for triggering operations based
69 // on number of iteration. each implicitly increments the iteration count
70 virtual void step() {}
71
72 // *** TraceActivity API ***
73 // FIXME: Pass activityProfiler interface into clientInterface?
74 virtual void pushCorrelationId(uint64_t id){}
75 virtual void popCorrelationId(){}
76 virtual void transferCpuTrace(
77 std::unique_ptr<CpuTraceBuffer> traceBuffer){}
78
79 // Correlation ids for user defined spans
80 virtual void pushUserCorrelationId(uint64_t){}
81 virtual void popUserCorrelationId(){}
82
83 // Saves information for the current thread to be used in profiler output
84 // Client must record any new kernel thread where the activity has occured.
85 virtual void recordThreadInfo() {}
86
87 // Record trace metadata, currently supporting only string key and values,
88 // values with the same key are overwritten
89 virtual void addMetadata(const std::string& key, const std::string& value) = 0;
90
91 // Add a child activity profiler, this enables frameworks in the application
92 // to enable custom framework events.
93 virtual void addChildActivityProfiler(
94 std::unique_ptr<IActivityProfiler> profiler) {}
95
96 // Log Invariant Violation to factories enabled. This helps record
97 // instances when the profiler behaves unexpectedly.
98 virtual void logInvariantViolation(
99 const std::string&,
100 const std::string&,
101 const std::string&,
102 const std::string& = "") {}
103};
104
105} // namespace libkineto
106