chore: import upstream snapshot with attribution

python/ray/_common/observability/__init__.py

@@ -0,0 +1,12 @@
+"""This module provides the Python API for emitting internal Ray events
+via the ONE-Event framework. Events are buffered and exported through
+the C++ RayEventRecorder.
+"""
+
+from ray._common.observability.internal_event import InternalEventBuilder
+from ray._common.observability.platform_events import PlatformEventBuilder
+
+__all__ = [
+    "InternalEventBuilder",
+    "PlatformEventBuilder",
+]

python/ray/_common/observability/internal_event.py

@@ -0,0 +1,111 @@
+"""Base class for building internal Ray events.
+
+This module provides the base class for creating event builders that can
+emit events to dashboard-agents aggregator agent service.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from ray._raylet import RayEvent
+from ray.core.generated.events_base_event_pb2 import RayEvent as RayEventProto
+from ray.util.annotations import DeveloperAPI
+
+
+@DeveloperAPI
+class InternalEventBuilder(ABC):
+    """Abstract base class for building internal Ray events.
+
+    Subclasses implement specific event types
+    and must implement get_entity_id() and serialize_event_data().
+    """
+
+    def __init__(
+        self,
+        source_type: int,
+        event_type: int,
+        nested_event_field_number: int,
+        severity: int = RayEventProto.Severity.INFO,
+        message: str = "",
+        session_name: str = "",
+    ):
+        """Initialize the event builder.
+
+        Args:
+            source_type: RayEvent.SourceType enum value. Use
+                RayEventProto.SourceType.<NAME> constants (e.g.,
+                RayEventProto.SourceType.JOBS,
+                RayEventProto.SourceType.GCS).
+            event_type: RayEvent.EventType enum value. Use
+                RayEventProto.EventType.<NAME> constants (e.g.,
+                RayEventProto.EventType.SUBMISSION_JOB_DEFINITION_EVENT,
+                RayEventProto.EventType.DRIVER_JOB_LIFECYCLE_EVENT).
+            nested_event_field_number: The field number in RayEvent proto for the
+                nested event message. Use RayEventProto.<FIELD>_FIELD_NUMBER
+                constants (e.g.,
+                RayEventProto.SUBMISSION_JOB_DEFINITION_EVENT_FIELD_NUMBER).
+            severity: RayEvent.Severity enum value (default INFO).
+            message: Optional message associated with the event.
+            session_name: The Ray session name.
+        """
+        self._source_type = source_type
+        self._event_type = event_type
+        self._nested_event_field_number = nested_event_field_number
+        self._severity = severity
+        self._message = message
+        self._session_name = session_name
+
+    @abstractmethod
+    def get_entity_id(self) -> str:
+        """Return the unique entity ID for this event.
+
+        The entity ID is used to associate related events (e.g., definition
+        and lifecycle events for the same job).
+
+        Returns:
+            A string identifier unique to this entity (e.g., node_id/task_id/actor_id/job_id).
+        """
+        pass
+
+    @abstractmethod
+    def serialize_event_data(self) -> bytes:
+        """Serialize the event-specific protobuf data to bytes.
+
+        Returns:
+            Serialized protobuf bytes of the nested event message
+            (e.g., SubmissionJobDefinitionEvent.SerializeToString()).
+        """
+        pass
+
+    def build(
+        self,
+        event_id: Optional[bytes] = None,
+        timestamp_ns: Optional[int] = None,
+    ) -> RayEvent:
+        """Build the Cython RayEvent object for submission.
+
+        Args:
+            event_id: Optional explicit event id bytes. When omitted, the C++ layer
+                generates a random id (matching the convention used by the other
+                RayEventInterface subclasses). Provide an explicit value to reuse
+                an id from an upstream source (e.g., a Kubernetes event uid).
+            timestamp_ns: Optional explicit event timestamp in nanoseconds since the
+                unix epoch. When omitted, the C++ layer captures the current time
+                at construction. Provide an explicit value for platform events that
+                carry their own source timestamp.
+
+        Returns:
+            A RayEvent object.
+        """
+        return RayEvent(
+            source_type=self._source_type,
+            event_type=self._event_type,
+            severity=self._severity,
+            entity_id=self.get_entity_id(),
+            message=self._message,
+            session_name=self._session_name,
+            serialized_data=self.serialize_event_data(),
+            nested_event_field_number=self._nested_event_field_number,
+            event_id=event_id if event_id is not None else b"",
+            timestamp_ns=int(timestamp_ns) if timestamp_ns is not None else 0,
+        )

python/ray/_common/observability/platform_events.py

@@ -0,0 +1,67 @@
+from typing import Dict, Optional
+
+from ray._common.observability.internal_event import InternalEventBuilder
+from ray.core.generated.events_base_event_pb2 import RayEvent as RayEventProto
+from ray.core.generated.platform_event_pb2 import PlatformEvent, Source
+from ray.util.annotations import DeveloperAPI
+
+
+@DeveloperAPI
+class PlatformEventBuilder(InternalEventBuilder):
+    """Builder for creating infrastructure PlatformEvents (e.g., from Kubernetes)."""
+
+    def __init__(
+        self,
+        event_uid: str,
+        platform: int = Source.Platform.PLATFORM_UNSPECIFIED,  # Source.Platform enum
+        object_kind: str = "",
+        object_name: str = "",
+        reason: str = "",
+        message: str = "",
+        severity: int = RayEventProto.Severity.INFO,
+        component: str = "",
+        source_metadata: Optional[Dict[str, str]] = None,
+        custom_fields: Optional[Dict[str, str]] = None,
+        session_name: str = "",
+    ):
+        super().__init__(
+            source_type=RayEventProto.SourceType.CLUSTER_LIFECYCLE,
+            event_type=RayEventProto.EventType.PLATFORM_EVENT,
+            nested_event_field_number=RayEventProto.PLATFORM_EVENT_FIELD_NUMBER,
+            severity=severity,
+            message=message,
+            session_name=session_name,
+        )
+        self._event_uid = event_uid
+        self._platform = platform
+        self._object_kind = object_kind
+        self._object_name = object_name
+        self._reason = reason
+        self._component = component
+        self._source_metadata = source_metadata
+        self._custom_fields = custom_fields
+
+    def get_entity_id(self) -> str:
+        return self._event_uid
+
+    def serialize_event_data(self) -> bytes:
+        source_proto = Source(
+            platform=self._platform,
+            component=self._component,
+        )
+        if self._source_metadata:
+            for k, v in self._source_metadata.items():
+                source_proto.metadata[k] = v
+
+        event = PlatformEvent(
+            source=source_proto,
+            object_kind=self._object_kind,
+            object_name=self._object_name,
+            message=self._message,
+            reason=self._reason,
+        )
+        if self._custom_fields:
+            for k, v in self._custom_fields.items():
+                event.custom_fields[k] = v
+
+        return event.SerializeToString()