Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: pass repository metadata to observability traces (#14431)

Graham Neubigd514ee406167
diff --git a/openhands/app_server/app_conversation/live_status_app_conversation_service.py b/openhands/app_server/app_conversation/live_status_app_conversation_service.py
index cf56283496..b426b72f97 100644
--- a/openhands/app_server/app_conversation/live_status_app_conversation_service.py
+++ b/openhands/app_server/app_conversation/live_status_app_conversation_service.py
@@ -508,6 +508,14 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
llm_model = request_agent.llm.model
agent_kind = 'openhands'
+ conversation_tags: dict[str, str] = dict(tags)
+ if request.selected_repository:
+ conversation_tags['repo_name'] = request.selected_repository
+ if request.git_provider:
+ conversation_tags['git_provider'] = request.git_provider.value
+ if request.selected_branch:
+ conversation_tags['selected_branch'] = request.selected_branch
+
app_conversation_info = AppConversationInfo(
id=info.id,
title=f'Conversation {info.id.hex[:5]}',
@@ -515,7 +523,6 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
created_by_user_id=user_id,
llm_model=llm_model,
agent_kind=agent_kind,
- tags=tags,
# Git parameters
selected_repository=request.selected_repository,
selected_branch=request.selected_branch,
@@ -523,6 +530,7 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
trigger=request.trigger,
pr_number=request.pr_number,
parent_conversation_id=request.parent_conversation_id,
+ tags=conversation_tags,
)
await self.app_conversation_info_service.save_app_conversation_info(
app_conversation_info
@@ -1290,12 +1298,50 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
return llm, mcp_servers
+ @staticmethod
+ def _build_observability_context(
+ conversation_id: UUID,
+ *,
+ agent_kind: str,
+ selected_repository: str | None = None,
+ selected_branch: str | None = None,
+ git_provider: ProviderType | None = None,
+ ) -> tuple[dict[str, Any], list[str]]:
+ """Build trace metadata and tag filters for a conversation.
+
+ Metadata uses explicit field names such as ``repo_name`` and
+ ``selected_branch``. Tags intentionally keep the concise
+ ``repo:`` / ``branch:`` prefixes used by LiteLLM metadata filters.
+ """
+ metadata: dict[str, Any] = {
+ 'app': 'openhands',
+ 'conversation_id': str(conversation_id),
+ 'agent_kind': agent_kind,
+ }
+ tags = ['app:openhands', f'agent_kind:{agent_kind}']
+
+ if selected_repository:
+ metadata['repo_name'] = selected_repository
+ tags.append(f'repo:{selected_repository}')
+ if selected_branch:
+ metadata['selected_branch'] = selected_branch
+ tags.append(f'branch:{selected_branch}')
+ if git_provider:
+ provider = git_provider.value
+ metadata['git_provider'] = provider
+ tags.append(f'git_provider:{provider}')
+
+ return metadata, tags
+
@staticmethod
def _apply_server_agent_overrides(
agent: Agent,
agent_type: AgentType,
conversation_id: UUID,
user_id: str | None,
+ repo_name: str | None = None,
+ git_provider: ProviderType | None = None,
+ selected_branch: str | None = None,
) -> Agent:
"""Apply server-only fields that have no place in ``AgentSettings``.
@@ -1318,6 +1364,9 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
llm_type=agent.llm.usage_id or 'agent',
conversation_id=conversation_id,
user_id=user_id,
+ repo_name=repo_name,
+ git_provider=git_provider.value if git_provider else None,
+ selected_branch=selected_branch,
)
overrides['llm'] = agent.llm.model_copy(
update={'litellm_extra_body': {'metadata': llm_metadata}}
@@ -1335,6 +1384,9 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
llm_type='condenser',
conversation_id=conversation_id,
user_id=user_id,
+ repo_name=repo_name,
+ git_provider=git_provider.value if git_provider else None,
+ selected_branch=selected_branch,
)
condenser_updates['litellm_extra_body'] = {
'metadata': condenser_metadata
@@ -1548,6 +1600,7 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
trigger: Optional conversation trigger.
remote_workspace: Optional remote workspace instance
selected_repository: Optional repository name
+ selected_branch: Optional selected branch name
plugins: Optional list of plugins to load
api_secrets: Optional secrets passed directly via the API.
These are merged with existing secrets (from database
@@ -1701,7 +1754,13 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
)
agent = self._apply_server_agent_overrides(
- agent, agent_type, conversation_id, user.id
+ agent,
+ agent_type,
+ conversation_id,
+ user.id,
+ repo_name=selected_repository,
+ git_provider=git_provider,
+ selected_branch=selected_branch,
)
# --- hooks (require remote workspace; must precede request build) -----
@@ -1739,6 +1798,14 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
for p in plugins
]
+ observability_metadata, observability_tags = self._build_observability_context(
+ conversation_id,
+ agent_kind='openhands',
+ selected_repository=selected_repository,
+ selected_branch=selected_branch,
+ git_provider=git_provider,
+ )
+
# --- populate ConversationSettings and build request ----------------
conv_settings = user.conversation_settings.model_copy(
update={
@@ -1773,6 +1840,8 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
create_kwargs: dict[str, Any] = {'agent': agent, 'user_id': laminar_user_id}
if observability_metadata:
create_kwargs['observability_metadata'] = observability_metadata
+ if observability_tags:
+ create_kwargs['observability_tags'] = observability_tags
request = conv_settings.create_request(
StartConversationRequest, **create_kwargs
)
@@ -1885,7 +1954,7 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
trigger: Optional conversation trigger.
git_provider: Optional git provider type
selected_repository: Optional repository name
- selected_branch: Optional branch name
+ selected_branch: Optional selected branch name
remote_workspace: Optional remote workspace instance, used to
resolve the HEAD commit for the Laminar trace metadata.
plugins: Optional list of plugins to load
@@ -1985,6 +2054,14 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
for p in plugins
]
+ observability_metadata, observability_tags = self._build_observability_context(
+ conversation_id,
+ agent_kind='acp',
+ selected_repository=selected_repository,
+ selected_branch=selected_branch,
+ git_provider=git_provider,
+ )
+
# Mirror the regular path: populate ConversationSettings and delegate
# to create_request() so that max_iterations, confirmation_mode, and
# security_analyzer flow through to ACP conversations too.
@@ -2017,6 +2094,8 @@ class LiveStatusAppConversationService(AppConversationServiceBase):
}
if observability_metadata:
create_kwargs['observability_metadata'] = observability_metadata
+ if observability_tags:
+ create_kwargs['observability_tags'] = observability_tags
return conv_settings.create_request(StartConversationRequest, **create_kwargs)
async def _process_pending_messages(
diff --git a/openhands/app_server/utils/llm_metadata.py b/openhands/app_server/utils/llm_metadata.py
index b519f9a1c8..7b61f21717 100644
--- a/openhands/app_server/utils/llm_metadata.py
+++ b/openhands/app_server/utils/llm_metadata.py
@@ -30,16 +30,24 @@ def get_llm_metadata(
llm_type: str,
conversation_id: UUID | str | None = None,
user_id: str | None = None,
+ repo_name: str | None = None,
+ git_provider: str | None = None,
+ selected_branch: str | None = None,
) -> dict[str, Any]:
"""Generate LLM metadata for OpenHands V1 conversations.
This metadata is passed to the LiteLLM proxy for tracing and analytics.
+ Repository tags use concise filter prefixes (``repo:`` and ``branch:``)
+ while metadata keys use explicit field names.
Args:
model_name: Name of the LLM model
llm_type: Type of LLM usage (e.g., 'agent', 'condenser', 'planning_condenser')
conversation_id: Optional conversation identifier
user_id: Optional user identifier
+ repo_name: Optional selected repository name
+ git_provider: Optional git provider identifier
+ selected_branch: Optional selected branch name
Returns:
Dictionary containing metadata for LLM initialization
@@ -70,4 +78,14 @@ def get_llm_metadata(
if user_id is not None:
metadata['trace_user_id'] = user_id
+ if repo_name:
+ metadata['repo_name'] = repo_name
+ metadata['tags'].append(f'repo:{repo_name}')
+ if git_provider:
+ metadata['git_provider'] = git_provider
+ metadata['tags'].append(f'git_provider:{git_provider}')
+ if selected_branch:
+ metadata['selected_branch'] = selected_branch
+ metadata['tags'].append(f'branch:{selected_branch}')
+
return metadata
diff --git a/tests/unit/app_server/test_live_status_app_conversation_service.py b/tests/unit/app_server/test_live_status_app_conversation_service.py
index b4390700d7..91d7275d9b 100644
--- a/tests/unit/app_server/test_live_status_app_conversation_service.py
+++ b/tests/unit/app_server/test_live_status_app_conversation_service.py
@@ -890,6 +890,51 @@ class TestLiveStatusAppConversationService:
# Assert
assert path == '/workspace/project/agents-tmp-config/PLAN.md'
+ def test_build_observability_context_includes_repository(self):
+ conversation_id = uuid4()
+
+ metadata, tags = self.service._build_observability_context(
+ conversation_id,
+ agent_kind='openhands',
+ selected_repository='OpenHands/software-agent-sdk',
+ selected_branch='main',
+ git_provider=ProviderType.GITHUB,
+ )
+
+ assert metadata == {
+ 'app': 'openhands',
+ 'conversation_id': str(conversation_id),
+ 'agent_kind': 'openhands',
+ 'repo_name': 'OpenHands/software-agent-sdk',
+ 'selected_branch': 'main',
+ 'git_provider': 'github',
+ }
+ assert 'repo:OpenHands/software-agent-sdk' in tags
+ assert 'branch:main' in tags
+ assert 'git_provider:github' in tags
+
+ def test_apply_server_overrides_adds_repo_metadata(self):
+ llm = LLM(model='openhands/gpt-4', api_key='k', usage_id='agent')
+ agent = Agent(llm=llm, tools=[])
+
+ updated = self.service._apply_server_agent_overrides(
+ agent,
+ AgentType.DEFAULT,
+ uuid4(),
+ 'user-1',
+ repo_name='OpenHands/software-agent-sdk',
+ git_provider=ProviderType.GITHUB,
+ selected_branch='main',
+ )
+
+ metadata = updated.llm.litellm_extra_body['metadata']
+ assert metadata['repo_name'] == 'OpenHands/software-agent-sdk'
+ assert metadata['git_provider'] == 'github'
+ assert metadata['selected_branch'] == 'main'
+ assert 'repo:OpenHands/software-agent-sdk' in metadata['tags']
+ assert 'branch:main' in metadata['tags']
+ assert 'git_provider:github' in metadata['tags']
+
@patch(
'openhands.app_server.app_conversation.live_status_app_conversation_service.get_default_tools',
return_value=[],
@@ -2145,6 +2190,95 @@ class TestLiveStatusAppConversationService:
)
assert saved_info.id == conversation_id
+ @patch(
+ 'openhands.app_server.app_conversation.live_status_app_conversation_service.AsyncRemoteWorkspace'
+ )
+ @patch(
+ 'openhands.app_server.app_conversation.live_status_app_conversation_service.ConversationInfo'
+ )
+ @pytest.mark.asyncio
+ async def test_start_app_conversation_preserves_acp_and_repository_tags(
+ self, mock_conversation_info_class, mock_remote_workspace_class
+ ):
+ """ACP conversations keep provider tags when repository tags are added."""
+ from openhands.sdk.settings import ACPAgentSettings
+
+ conversation_id = uuid4()
+ self.mock_user.agent_settings = ACPAgentSettings(
+ acp_server='claude-code',
+ llm=LLM(model='claude-sonnet-4-5', api_key=SecretStr('sk-ui-key')),
+ )
+ self.mock_user_context.get_user_id = AsyncMock(return_value='test_user_123')
+ self.mock_user_context.get_user_info = AsyncMock(return_value=self.mock_user)
+
+ mock_sandbox_spec = Mock(spec=SandboxSpecInfo)
+ mock_sandbox_spec.working_dir = '/test/workspace'
+ self.mock_sandbox.sandbox_spec_id = str(uuid4())
+ self.mock_sandbox.id = str(uuid4())
+ self.mock_sandbox.session_api_key = 'test_session_key'
+ exposed_url = ExposedUrl(
+ name=AGENT_SERVER, url='http://agent-server:8000', port=60000
+ )
+ self.mock_sandbox.exposed_urls = [exposed_url]
+ self.mock_sandbox_service.get_sandbox = AsyncMock(
+ return_value=self.mock_sandbox
+ )
+ self.mock_sandbox_spec_service.get_sandbox_spec = AsyncMock(
+ return_value=mock_sandbox_spec
+ )
+ mock_remote_workspace_class.return_value = Mock()
+
+ async def mock_wait_for_sandbox(task):
+ task.sandbox_id = self.mock_sandbox.id
+ yield task
+
+ async def mock_run_setup_scripts(
+ task, sandbox, workspace, agent_server_url, conversation_id
+ ):
+ yield task
+
+ self.service._wait_for_sandbox_start = mock_wait_for_sandbox
+ self.service.run_setup_scripts = mock_run_setup_scripts
+ self.service._seed_sandbox_profiles = AsyncMock()
+
+ mock_agent = Mock()
+ mock_agent.agent_kind = 'acp'
+ mock_agent.acp_model = 'claude-sonnet-4-5'
+ mock_start_request = Mock(spec=StartConversationRequest)
+ mock_start_request.agent = mock_agent
+ mock_start_request.model_dump.return_value = {'test': 'data'}
+ self.service._build_start_conversation_request_for_user = AsyncMock(
+ return_value=mock_start_request
+ )
+
+ mock_conversation_info = Mock()
+ mock_conversation_info.id = conversation_id
+ mock_conversation_info_class.model_validate.return_value = (
+ mock_conversation_info
+ )
+ mock_response = Mock()
+ mock_response.json.return_value = {'id': str(conversation_id)}
+ mock_response.raise_for_status = Mock()
+ self.mock_httpx_client.post = AsyncMock(return_value=mock_response)
+ self.mock_event_callback_service.save_event_callback = AsyncMock()
+
+ request = AppConversationStartRequest(
+ selected_repository='OpenHands/OpenHands',
+ selected_branch='main',
+ git_provider=ProviderType.GITHUB,
+ )
+
+ async for _ in self.service._start_app_conversation(request):
+ pass
+
+ saved_info = self.mock_app_conversation_info_service.save_app_conversation_info.call_args[
+ 0
+ ][0]
+ assert saved_info.tags['acpserver'] == 'claude-code'
+ assert saved_info.tags['repo_name'] == 'OpenHands/OpenHands'
+ assert saved_info.tags['git_provider'] == 'github'
+ assert saved_info.tags['selected_branch'] == 'main'
+
@patch(
'openhands.app_server.app_conversation.live_status_app_conversation_service.AsyncRemoteWorkspace'
)
@@ -2180,7 +2314,6 @@ class TestLiveStatusAppConversationService:
name=AGENT_SERVER, url='http://agent-server:8000', port=60000
)
self.mock_sandbox.exposed_urls = [exposed_url]
-
self.mock_sandbox_service.get_sandbox = AsyncMock(
return_value=self.mock_sandbox
)
@@ -2209,7 +2342,6 @@ class TestLiveStatusAppConversationService:
mock_start_request = Mock(spec=StartConversationRequest)
mock_start_request.agent = mock_acp_agent
mock_start_request.model_dump.return_value = {}
-
self.service._build_start_conversation_request_for_user = AsyncMock(
return_value=mock_start_request
)
@@ -2219,7 +2351,6 @@ class TestLiveStatusAppConversationService:
mock_conversation_info_class.model_validate.return_value = (
mock_conversation_info
)
-
mock_response = Mock()
mock_response.json.return_value = {'id': str(conversation_id)}
mock_response.raise_for_status = Mock()
diff --git a/uv.lock b/uv.lock
index 529272d5bb..cfab4b3adb 100644
--- a/uv.lock
+++ b/uv.lock
@@ -10,6 +10,15 @@ resolution-markers = [
"python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
]
+[options]
+exclude-newer = "0001-01-01T00:00:00Z" # This has no effect and is included for backwards compatibility when using relative exclude-newer values.
+exclude-newer-span = "P7D"
+
+[options.exclude-newer-package]
+openhands-tools = false
+openhands-agent-server = false
+openhands-sdk = false
+
[[package]]
name = "agent-client-protocol"
version = "0.10.1"