microsoft
diff --git a/‎cmake/onnxruntime_unittests.cmake‎
Lines changed: 2 additions & 0 deletions b/‎cmake/onnxruntime_unittests.cmake‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎include/onnxruntime/core/common/gpu_profiler_common.h‎
Lines changed: 5 additions & 1 deletion b/‎include/onnxruntime/core/common/gpu_profiler_common.h‎
Lines changed: 5 additions & 1 deletion
diff --git a/‎include/onnxruntime/core/common/profiler_common.h‎
Lines changed: 67 additions & 4 deletions b/‎include/onnxruntime/core/common/profiler_common.h‎
Lines changed: 67 additions & 4 deletions
diff --git a/‎include/onnxruntime/core/session/onnxruntime_cxx_api.h‎
Lines changed: 90 additions & 0 deletions b/‎include/onnxruntime/core/session/onnxruntime_cxx_api.h‎
Lines changed: 90 additions & 0 deletions
diff --git a/‎include/onnxruntime/core/session/onnxruntime_cxx_inline.h‎
Lines changed: 92 additions & 0 deletions b/‎include/onnxruntime/core/session/onnxruntime_cxx_inline.h‎
Lines changed: 92 additions & 0 deletions
@@ -2137,6 +2137,8 @@ if (onnxruntime_BUILD_SHARED_LIB AND
           "${TEST_SRC_DIR}/autoep/library/example_plugin_ep_kernel_registry/ep_data_transfer.cc"
           "${TEST_SRC_DIR}/autoep/library/example_plugin_ep_kernel_registry/ep_kernel_registration.h"
           "${TEST_SRC_DIR}/autoep/library/example_plugin_ep_kernel_registry/ep_kernel_registration.cc"
+          "${TEST_SRC_DIR}/autoep/library/example_plugin_ep_kernel_registry/ep_profiling.h"
+          "${TEST_SRC_DIR}/autoep/library/example_plugin_ep_kernel_registry/ep_profiling.cc"
           "${TEST_SRC_DIR}/autoep/library/example_plugin_ep_kernel_registry/kernels/utils.h"
           "${TEST_SRC_DIR}/autoep/library/example_plugin_ep_kernel_registry/kernels/squeeze.h"
           "${TEST_SRC_DIR}/autoep/library/example_plugin_ep_kernel_registry/kernels/squeeze.cc"
 
@@ -377,6 +377,10 @@ class GPUProfilerBase : public EpProfiler {
   virtual ~GPUProfilerBase() {}
 
   void MergeEvents(std::map<uint64_t, Events>& events_to_merge, Events& events) {
+    // TODO: Fix incorrect assumption that ORT events are sorted by non-decreasing start time.
+    // They are actually sorted by non-decreasing end time, which prevents this algorithm
+    // from properly merging and annotating all EP events.
+    // See Profiler::EndTimeAndRecordEvent() in onnxruntime/core/common/profiler.cc
     Events merged_events;
 
     auto event_iter = events.begin();
@@ -457,7 +461,7 @@ class GPUProfilerBase : public EpProfiler {
     manager.PushCorrelation(client_handle_, id, profiling_start_time_);
   }
 
-  virtual void Stop(uint64_t) override {
+  virtual void Stop(uint64_t, const EventRecord&) override {
     auto& manager = TManager::GetInstance();
     manager.PopCorrelation();
   }
 
@@ -11,6 +11,8 @@
 namespace onnxruntime {
 namespace profiling {
 
+// Profiling event categories.
+// Note: Keep in sync with OrtProfilingEventCategory in onnxruntime_ep_c_api.h.
 enum EventCategory {
   SESSION_EVENT = 0,
   NODE_EVENT,
@@ -79,10 +81,71 @@ using Events = std::vector<EventRecord>;
 class EpProfiler {
  public:
   virtual ~EpProfiler() = default;
-  virtual bool StartProfiling(TimePoint profiling_start_time) = 0;      // called when profiling starts
-  virtual void EndProfiling(TimePoint start_time, Events& events) = 0;  // called when profiling ends, save all captures numbers to "events"
-  virtual void Start(uint64_t) {}                                       // called before op start, accept an id as argument to identify the op
-  virtual void Stop(uint64_t) {}                                        // called after op stop, accept an id as argument to identify the op
+
+  /// <summary>
+  /// Called when profiling starts.
+  /// Allows EP profiler to initialize profiling utilities and record the profiling start time.
+  /// </summary>
+  /// <param name="profiling_start_time">Timepoint denoting the start of profiling.</param>
+  /// <returns>True if profiling was started successfully.</returns>
+  virtual bool StartProfiling(TimePoint profiling_start_time) = 0;
+
+  /// <summary>
+  /// Called when profiling ends to collect the EP's new profiling events since the last call to StartProfiling.
+  /// </summary>
+  /// <param name="start_time">Timepoint denoting the start of profiling. Same value passed to StartProfiling.</param>
+  /// <param name="events">Modifiable events container to which the EP profiler appends its events.</param>
+  virtual void EndProfiling(TimePoint start_time, Events& events) = 0;
+
+  /// <summary>
+  /// Optional to override (default implementation does nothing).
+  ///
+  /// Called when an ORT event (e.g., session initialization, node kernel execution, etc.) starts.
+  /// ORT pairs every Start call with a corresponding call to Stop with the same relative ORT event ID.
+  /// EP profiler implementations may use the calls to Start and Stop to maintain a stack of ORT event IDs
+  /// that can be correlated with EP events (e.g., GPU kernel events).
+  ///
+  /// A relative ORT event ID is computed as a timestamp offset relative to the profiling start time:
+  ///     relative_ort_event_id =
+  ///         std::chrono::duration_cast<std::chrono::microseconds>(event_start_time - profiling_start_time).count();
+  ///
+  /// Because relative ORT event IDs are relative to profiling start, different profiling sessions may reuse the same
+  /// values. If the EP's profiling utilities (e.g., CUPTI or ROCTracer) require correlation IDs that are practically
+  /// unique across concurrent profiling sessions (collisions require sub-microsecond event concurrency), then the
+  /// EP profiler should compute an absolute correlation ID:
+  ///     absolute_ort_correlation_id =
+  ///        relative_ort_event_id +
+  ///        std::chrono::duration_cast<std::chrono::microseconds>(profiling_start_time.time_since_epoch()).count();
+  ///
+  /// Note: For plugin EPs using the binary-stable C API (OrtEpProfilerImpl), ORT performs this conversion
+  /// automatically. The C API's StartEvent/StopEvent receive the absolute correlation ID directly.
+  /// </summary>
+  /// <param name="relative_ort_event_id">
+  /// Relative ID of the ORT event that is starting (microseconds since profiling start).
+  /// The same value is passed to a corresponding call to Stop.
+  /// </param>
+  virtual void Start(uint64_t /*relative_ort_event_id*/) {}
+
+  /// <summary>
+  /// Optional to override (default implementation does nothing).
+  ///
+  /// Called when an ORT event (e.g., session initialization, node kernel execution, etc.) ends.
+  /// ORT pairs every Start call with a corresponding call to Stop with the same relative ORT event ID.
+  /// EP profiler implementations may use the calls to Start and Stop to maintain a stack of ORT event IDs
+  /// that can be correlated with EP events (e.g., GPU kernel events).
+  ///
+  /// The ort_event parameter provides the full ORT event record including metadata such as op_name
+  /// (in event args), event name, category, timestamps, etc. EP profilers can use this to annotate
+  /// their own events with ORT event context.
+  /// </summary>
+  /// <param name="relative_ort_event_id">
+  /// Relative ID of the ORT event that is ending (microseconds since profiling start).
+  /// The same value was passed to a corresponding call to Start.
+  /// </param>
+  /// <param name="ort_event">
+  /// The ORT event record containing metadata for this event.
+  /// </param>
+  virtual void Stop(uint64_t /*relative_ort_event_id*/, const EventRecord& /*ort_event*/) {}
 };
 
 // Demangle C++ symbols
 
@@ -662,6 +662,7 @@ ORT_DEFINE_RELEASE_FROM_API_STRUCT(KernelDef, GetEpApi);
 ORT_DEFINE_RELEASE_FROM_API_STRUCT(KernelDefBuilder, GetEpApi);
 ORT_DEFINE_RELEASE_FROM_API_STRUCT(KernelRegistry, GetEpApi);
 ORT_DEFINE_RELEASE_FROM_API_STRUCT(OpSchema, GetEpApi);
+ORT_DEFINE_RELEASE_FROM_API_STRUCT(ProfilingEvent, GetEpApi);
 
 // This is defined explicitly since OrtTensorRTProviderOptionsV2 is not a C API type,
 // but the struct has V2 in its name to indicate that it is the second version of the options.
@@ -1231,6 +1232,95 @@ struct EpAssignedSubgraphImpl : Ort::detail::Base<T> {
  */
 using ConstEpAssignedSubgraph = detail::EpAssignedSubgraphImpl<Ort::detail::Unowned<const OrtEpAssignedSubgraph>>;
 
+namespace detail {
+template <typename T>
+struct ConstProfilingEventImpl : Ort::detail::Base<T> {
+  using B = Ort::detail::Base<T>;
+  using B::B;
+
+  /// \brief Get the event category. Wraps OrtEpApi::ProfilingEvent_GetCategory
+  OrtProfilingEventCategory GetCategory() const;
+
+  /// \brief Get the event name. Wraps OrtEpApi::ProfilingEvent_GetName
+  /// \return Null-terminated UTF-8 string owned by the OrtProfilingEvent instance. Do not free.
+  const char* GetName() const;
+
+  /// \brief Get the start timestamp in microseconds. Wraps OrtEpApi::ProfilingEvent_GetTimestampUs
+  int64_t GetTimestampUs() const;
+
+  /// \brief Get the duration in microseconds. Wraps OrtEpApi::ProfilingEvent_GetDurationUs
+  int64_t GetDurationUs() const;
+
+  /// \brief Get the value of an event argument by key. Wraps OrtEpApi::ProfilingEvent_GetArgValue
+  /// \param[in] key Null-terminated argument key to look up.
+  /// \return Null-terminated UTF-8 string owned by the OrtProfilingEvent, or nullptr if key not found.
+  const char* GetArgValue(const char* key) const;
+};
+}  // namespace detail
+
+/** \brief Non-owning const wrapper around ::OrtProfilingEvent.
+ *
+ * Use this to read fields from the OrtProfilingEvent pointer passed to OrtEpProfilerImpl::StopEvent.
+ *
+ * This is based on the Trace Event Format's "complete event".
+ * \since Version 1.25.
+ */
+using ConstProfilingEvent = detail::ConstProfilingEventImpl<Ort::detail::Unowned<const OrtProfilingEvent>>;
+
+/** \brief Owning wrapper around ::OrtProfilingEvent.
+ *
+ * Use this to create profiling events via OrtEpApi::CreateProfilingEvent. The event is released
+ * automatically on destruction.
+ * \since Version 1.25.
+ */
+struct ProfilingEvent : detail::ConstProfilingEventImpl<OrtProfilingEvent> {
+  explicit ProfilingEvent(std::nullptr_t) {}  ///< No instance is created
+  explicit ProfilingEvent(OrtProfilingEvent* p)
+      : ConstProfilingEventImpl<OrtProfilingEvent>{p} {}  ///< Take ownership
+
+  /// \brief Wraps OrtEpApi::CreateProfilingEvent
+  ProfilingEvent(OrtProfilingEventCategory category,
+                 int32_t process_id,
+                 int32_t thread_id,
+                 const char* event_name,
+                 int64_t timestamp_us,
+                 int64_t duration_us,
+                 const std::unordered_map<std::string, std::string>& args = {});
+
+  /// \brief Wraps OrtEpApi::CreateProfilingEvent
+  ProfilingEvent(OrtProfilingEventCategory category,
+                 int32_t process_id,
+                 int32_t thread_id,
+                 const char* event_name,
+                 int64_t timestamp_us,
+                 int64_t duration_us,
+                 const char* const* arg_keys,
+                 const char* const* arg_values,
+                 size_t num_args);
+
+  ConstProfilingEvent GetConst() const { return ConstProfilingEvent{this->p_}; }
+};
+
+namespace detail {
+template <typename T>
+struct ProfilingEventsContainerImpl : Ort::detail::Base<T> {
+  using B = Ort::detail::Base<T>;
+  using B::B;
+
+  /// \brief Adds profiling events to this container. Events are copied.
+  /// Wraps OrtEpApi::ProfilingEventsContainer_AddEvents.
+  Ort::Status AddEvents(const OrtProfilingEvent* const* events, size_t num_events);
+  Ort::Status AddEvents(const std::vector<ProfilingEvent>& events);
+};
+}  // namespace detail
+
+/** \brief Non-owning wrapper around ::OrtProfilingEventsContainer.
+ *
+ * Use this to add EP profiling events to a container owned by ORT during the call to OrtEpProfilerImpl::EndProfiling.
+ * \since Version 1.25.
+ */
+using UnownedProfilingEventsContainer = detail::ProfilingEventsContainerImpl<detail::Unowned<OrtProfilingEventsContainer>>;
+
 /** \brief The Env (Environment)
  *
  * The Env holds the logging state used by all other objects.
 
@@ -802,6 +802,98 @@ inline std::string EpAssignedNodeImpl<T>::GetOperatorType() const {
 }
 }  // namespace detail
 
+// ProfilingEvent implementations
+namespace detail {
+template <typename T>
+inline OrtProfilingEventCategory ConstProfilingEventImpl<T>::GetCategory() const {
+  OrtProfilingEventCategory out{};
+  ThrowOnError(GetEpApi().ProfilingEvent_GetCategory(this->p_, &out));
+  return out;
+}
+
+template <typename T>
+inline const char* ConstProfilingEventImpl<T>::GetName() const {
+  const char* name = nullptr;
+  ThrowOnError(GetEpApi().ProfilingEvent_GetName(this->p_, &name));
+  return name;
+}
+
+template <typename T>
+inline int64_t ConstProfilingEventImpl<T>::GetTimestampUs() const {
+  int64_t out = 0;
+  ThrowOnError(GetEpApi().ProfilingEvent_GetTimestampUs(this->p_, &out));
+  return out;
+}
+
+template <typename T>
+inline int64_t ConstProfilingEventImpl<T>::GetDurationUs() const {
+  int64_t out = 0;
+  ThrowOnError(GetEpApi().ProfilingEvent_GetDurationUs(this->p_, &out));
+  return out;
+}
+
+template <typename T>
+inline const char* ConstProfilingEventImpl<T>::GetArgValue(const char* key) const {
+  const char* value = nullptr;
+  ThrowOnError(GetEpApi().ProfilingEvent_GetArgValue(this->p_, key, &value));
+  return value;
+}
+}  // namespace detail
+
+inline ProfilingEvent::ProfilingEvent(OrtProfilingEventCategory category,
+                                      int32_t process_id,
+                                      int32_t thread_id,
+                                      const char* event_name,
+                                      int64_t timestamp_us,
+                                      int64_t duration_us,
+                                      const std::unordered_map<std::string, std::string>& args) {
+  const size_t num_args = args.size();
+  std::vector<const char*> arg_keys;
+  std::vector<const char*> arg_vals;
+
+  arg_keys.reserve(num_args);
+  arg_vals.reserve(num_args);
+  for (const auto& [k, v] : args) {
+    arg_keys.push_back(k.c_str());
+    arg_vals.push_back(v.c_str());
+  }
+
+  ThrowOnError(GetEpApi().CreateProfilingEvent(category, process_id, thread_id, event_name,
+                                               timestamp_us, duration_us,
+                                               arg_keys.data(), arg_vals.data(), num_args, &p_));
+}
+
+inline ProfilingEvent::ProfilingEvent(OrtProfilingEventCategory category,
+                                      int32_t process_id,
+                                      int32_t thread_id,
+                                      const char* event_name,
+                                      int64_t timestamp_us,
+                                      int64_t duration_us,
+                                      const char* const* arg_keys,
+                                      const char* const* arg_values,
+                                      size_t num_args) {
+  ThrowOnError(GetEpApi().CreateProfilingEvent(category, process_id, thread_id, event_name,
+                                               timestamp_us, duration_us,
+                                               arg_keys, arg_values, num_args, &p_));
+}
+
+// ProfilingEventsContainer implementations
+namespace detail {
+template <typename T>
+inline Status ProfilingEventsContainerImpl<T>::AddEvents(const OrtProfilingEvent* const* events, size_t num_events) {
+  return Status{GetEpApi().ProfilingEventsContainer_AddEvents(this->p_, events, num_events)};
+}
+
+template <typename T>
+inline Status ProfilingEventsContainerImpl<T>::AddEvents(const std::vector<ProfilingEvent>& events) {
+  static_assert(sizeof(ProfilingEvent) == sizeof(OrtProfilingEvent*) &&
+                    alignof(ProfilingEvent) == alignof(OrtProfilingEvent*),
+                "ProfilingEvent must have the same size and alignment as a raw pointer for reinterpret_cast");
+  const auto* event_ptrs = reinterpret_cast<const OrtProfilingEvent* const*>(events.data());
+  return AddEvents(event_ptrs, events.size());
+}
+}  // namespace detail
+
 inline Env::Env(OrtLoggingLevel logging_level, _In_ const char* logid) {
   ThrowOnError(GetApi().CreateEnv(logging_level, logid, &p_));
   if (strcmp(logid, "onnxruntime-node") == 0) {