Implementation:OpenHands OpenHands TelemetryIdentity

Knowledge Sources	OpenHands
Domains	Storage, Telemetry, Licensing
Last Updated	2026-02-11 21:00 GMT

Overview

Single-row ORM table for persisting Replicated customer and instance identification data, provided by the OpenHands enterprise storage layer.

Description

TelemetryIdentity is a SQLAlchemy ORM model that stores customer and instance identification information from the Replicated licensing platform. The table is designed to hold exactly one row, enforced by a CheckConstraint('id = 1') at the database level. This single-row pattern ensures there is always at most one identity record for the deployment, preventing accidental duplicates.

The set_customer_info() method upserts customer and instance data (such as customer ID, instance ID, and license metadata) into the single row. The has_customer_info property provides a quick boolean check for whether customer information has been configured.

This model is used during server startup and telemetry reporting to identify the deployment to the Replicated platform. It supports the licensing and usage reporting features of the enterprise edition.

Usage

Use TelemetryIdentity during initial server setup to persist the customer identity received from Replicated, and during telemetry reporting to retrieve the stored identity. Check has_customer_info before attempting to send telemetry data, as the identity may not yet be configured on fresh installations.

Code Reference

Source Location

• Repository: OpenHands
• File: enterprise/storage/telemetry_identity.py
• Lines: 1-98

Signature

class TelemetryIdentity(Base):
    __tablename__ = "telemetry_identity"
    __table_args__ = (
        CheckConstraint('id = 1', name='single_row_constraint'),
    )

    id: Mapped[int]  # Always 1
    customer_id: Mapped[Optional[str]]
    instance_id: Mapped[Optional[str]]
    license_id: Mapped[Optional[str]]
    created_at: Mapped[datetime]
    updated_at: Mapped[datetime]

    def set_customer_info(
        self,
        customer_id: str,
        instance_id: str,
        **kwargs
    ) -> None:
        """Upserts customer and instance identity data into the single row."""
        ...

    @property
    def has_customer_info(self) -> bool:
        """Returns True if customer_id and instance_id are populated."""
        ...

Import

from enterprise.storage.telemetry_identity import TelemetryIdentity

I/O Contract

Inputs

set_customer_info()

Name	Type	Required	Description
customer_id	str	Yes	Replicated customer identifier
instance_id	str	Yes	Replicated instance identifier for this deployment
**kwargs	dict	No	Additional license metadata (e.g., license_id, entitlements)

Outputs

Method/Property	Return Type	Description
set_customer_info()	None	Upserts identity data into the single-row table
has_customer_info	bool	True if both customer_id and instance_id are non-null

ORM Fields

Field	Type	Description
id	int	Always 1 (enforced by CheckConstraint)
customer_id	Optional[str]	Replicated customer identifier
instance_id	Optional[str]	Replicated instance identifier
license_id	Optional[str]	Replicated license identifier
created_at	datetime	Row creation timestamp
updated_at	datetime	Last update timestamp

Usage Examples

Setting Customer Info During Setup

from enterprise.storage.telemetry_identity import TelemetryIdentity

# Query or create the single row
identity = session.query(TelemetryIdentity).first()
if identity is None:
    identity = TelemetryIdentity(id=1)
    session.add(identity)

# Set the Replicated customer info
identity.set_customer_info(
    customer_id="cust-abc-123",
    instance_id="inst-xyz-789",
    license_id="lic-456"
)
session.commit()

Checking Before Telemetry Reporting

identity = session.query(TelemetryIdentity).first()

if identity and identity.has_customer_info:
    send_telemetry(
        customer_id=identity.customer_id,
        instance_id=identity.instance_id
    )
else:
    logger.warning("Telemetry identity not configured; skipping report")

Related Pages

Environment

• Environment:OpenHands_OpenHands_SaaS_Server_Environment