logfire-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Open Logfire UI

打开Logfire UI

Use this skill for direct Logfire UI, browser, live-view, link, and Explore-page requests.

当用户直接请求Logfire UI、浏览器、实时视图、链接和Explore页面时，使用此技能。

User-Facing Progress

用户可见的进度更新

Keep progress updates quiet. Do not narrate why this skill was selected, restate routing rules, quote local instructions, explain token scope, or announce routine helper calls. If an update is needed, use one short sentence focused on the action, such as "Opening Logfire with the error filter."

After opening Logfire, do not run or narrate an extra page-state check unless the browser appears stuck, asks for login, or the user explicitly asked you to verify the page.

保持进度更新简洁。不要说明选择此技能的原因、重述路由规则、引用本地指令、解释令牌范围或宣布常规助手调用。如果需要更新，使用一句简短的动作相关语句，例如“正在打开带有错误筛选器的Logfire。”

打开Logfire后，除非浏览器出现卡顿、要求登录或用户明确要求验证页面，否则不要运行或额外说明页面状态检查。

Browser Targeting

浏览器定位

In Codex Desktop, use the Browser plugin's Codex in-app browser (

iab

) and the currently selected tab whenever possible.

Browser access is indirect: do not expect a browser-named MCP tool. If the Browser plugin is listed as available, load the

browser:browser

skill and use its Node REPL

js

mcp__node_repl__js

bootstrap to bind

agent.browsers.get("iab")

. If

js

is not visible, use tool discovery for

node_repl js

before declaring the in-app browser unavailable.

Do not use

agent-browser

chrome-devtools

mcp__chrome_devtools__*

mcp__playwright__*

, macOS

open

xdg-open

, standalone Playwright/Chromium, a shell-launched browser, web preview cards, or a newly created external browser window unless the user explicitly asks for an external browser. Do not create a new in-app tab when a Logfire live view is already selected and can be updated in place.

Only report the in-app browser unavailable after the Browser plugin is not listed or its skill cannot be loaded, the Node REPL

js

execution tool is unavailable after tool discovery, or the Browser skill bootstrap fails before navigation starts. Then return the clean Logfire URL and explain that the in-app browser could not be controlled. Treat

chrome-devtools

, Playwright MCP, standalone Playwright, and web preview cards as "Browser unavailable", not as fallbacks. Do not silently fall back to any external or dedicated browser window.

在Codex Desktop中，尽可能使用Browser插件的Codex内嵌浏览器（

iab

）和当前选中的标签页。

浏览器访问是间接的：不要期望有以browser命名的MCP工具。如果Browser插件列为可用，请加载

browser:browser

技能，并使用其Node REPL

js

mcp__node_repl__js

引导程序绑定

agent.browsers.get("iab")

。如果

js

不可见，请先通过工具发现

node_repl js

，再声明内嵌浏览器不可用。

除非用户明确要求使用外部浏览器，否则不要使用

agent-browser

、

chrome-devtools

、

mcp__chrome_devtools__*

、

mcp__playwright__*

、macOS的

open

、

xdg-open

、独立的Playwright/Chromium、通过shell启动的浏览器、网页预览卡片或新建的外部浏览器窗口。如果Logfire实时视图已选中且可就地更新，则不要新建内嵌标签页。

只有在Browser插件未列出或无法加载其技能、工具发现后Node REPL

js

执行工具不可用，或导航开始前Browser技能引导程序失败时，才报告内嵌浏览器不可用。然后返回清晰的Logfire URL，并解释无法控制内嵌浏览器。将

chrome-devtools

、Playwright MCP、独立Playwright和网页预览卡片视为“浏览器不可用”，而非备选方案。不要静默切换到任何外部或专用浏览器窗口。

Core Rule

核心规则

For project-level or aggregate UI requests, open or return Logfire directly by URL.

Do not query telemetry first:

Do not call
```
query_run
```
.
Do not say you will query Logfire or fetch spans first.

Only query first when the user asks to open a specific unknown item that must be found first, such as "open the slowest trace" or "open the latest error trace".

If the request is ambiguous, such as "show recent errors" or "view logs", ask whether the user wants Logfire opened in the UI or a query analysis in chat. Do not do both unless the user explicitly asks for both.

对于项目级或聚合UI请求，直接通过URL打开或返回Logfire。

请勿先查询遥测数据：

不要调用
```
query_run
```
。
不要说你将查询Logfire或先获取跨度数据。

只有当用户要求打开必须先找到的特定未知项时，才先进行查询，例如“打开最慢的追踪”或“打开最新的错误追踪”。

如果请求模糊，例如“显示最近的错误”或“查看日志”，请询问用户是想要在UI中打开Logfire还是在聊天中进行查询分析。除非用户明确要求两者都做，否则不要同时执行。

Project Discovery

项目发现

For UI requests without an explicit organization/project, first try to resolve the canonical project URL through Logfire MCP auth/current-project metadata. Use a project-link or current-project helper if the available MCP server exposes one. This is project discovery, not telemetry querying.

If the MCP can resolve exactly one current project, use that project URL. If it cannot resolve a project, resolves multiple candidates, or returns an auth/error state, ask the user for the organization/project or full Logfire project URL.

Do not infer the project URL from

LOGFIRE_BASE_URL

LOGFIRE_URL

, exporter config, repository names, or localhost reachability. Env/config values can identify the Logfire platform/API base, but they do not by themselves identify the target organization/project.

对于未明确指定组织/项目的UI请求，首先尝试通过Logfire MCP认证/当前项目元数据解析规范项目URL。如果可用的MCP服务器提供项目链接或当前项目助手，请使用它。这是项目发现，而非遥测查询。

如果MCP可以解析出唯一的当前项目，则使用该项目URL。如果无法解析项目、解析出多个候选项目或返回认证/错误状态，请询问用户提供组织/项目或完整的Logfire项目URL。

不要从

LOGFIRE_BASE_URL

、

LOGFIRE_URL

、导出器配置、仓库名称或本地主机可达性推断项目URL。环境/配置值可以标识Logfire平台/API基础，但它们本身无法标识目标组织/项目。

URL Workflow

URL工作流

If the full project URL is already known, use it directly.
If the user omits the project, resolve the current project through MCP as described above.
If the user gives a project name but not the organization/base URL, call
```
project_logfire_ui_link(project=project)
```
with the default clean-link behavior to derive the canonical project URL. This is a URL discovery helper, not a telemetry query.
For project live-view/filter URLs, call
```
project_logfire_ui_link(project=project, query=query, since=since, until=until, handoff=True)
```
when opening the link immediately in Codex Browser. Use the default clean-link behavior when returning a durable or shareable URL. If the user provides an existing clean Logfire project URL and asks for handoff, parse its project,
```
q
```
,
```
since
```
, and
```
until
```
values and pass them through this tool.
If the user gives or the query workflow has already found a real
```
trace_id
```
, call
```
project_logfire_link(trace_id=trace_id, project=project, handoff=True)
```
when opening the link immediately in Codex Browser. Use the default clean-link behavior when returning a durable or shareable URL.
Add
```
query
```
,
```
since
```
, and
```
until
```
through
```
project_logfire_ui_link
```
when useful. If manually assembling a clean URL, URL-encode
```
q
```
,
```
since
```
, and
```
until
```
.
If the user asked to open the URL and Browser is available, open it in the Codex in-app browser. Otherwise, return the URL rather than launching an external browser.

如果已知完整项目URL，直接使用它。
如果用户省略了项目，按照上述方法通过MCP解析当前项目。
如果用户提供了项目名称但未提供组织/基础URL，调用
```
project_logfire_ui_link(project=project)
```
并使用默认的清晰链接行为来生成规范项目URL。这是URL发现助手，而非遥测查询。
对于项目实时视图/筛选URL，当在Codex Browser中立即打开链接时，调用
```
project_logfire_ui_link(project=project, query=query, since=since, until=until, handoff=True)
```
。返回持久或可共享URL时使用默认的清晰链接行为。如果用户提供了现有的清晰Logfire项目URL并要求转交，请解析其项目、
```
q
```
、
```
since
```
和
```
until
```
值，并将它们传入此工具。
如果用户提供或查询工作流已找到真实的
```
trace_id
```
，当在Codex Browser中立即打开链接时，调用
```
project_logfire_link(trace_id=trace_id, project=project, handoff=True)
```
。返回持久或可共享URL时使用默认的清晰链接行为。
必要时通过
```
project_logfire_ui_link
```
添加
```
query
```
、
```
since
```
和
```
until
```
。如果手动组装清晰URL，请对
```
q
```
、
```
since
```
和
```
until
```
进行URL编码。
如果用户要求打开URL且Browser可用，则在Codex内嵌浏览器中打开它。否则，返回URL而非启动外部浏览器。

Already-Open Live View Control

已打开实时视图的控制

If a Logfire project live view is already open in Codex Browser, use the JSON command bridge. This is the only supported in-app interaction model because it updates the view without a full document reload and shows the user that the agent is actively changing the page.

Do not try to use page-global JavaScript APIs from Codex Browser. The only supported agent control surface is the JSON command input.

For Codex Browser /

iab

, fill the

Logfire live view agent command

input with a JSON patch such as

{"q":"level='error'","last":"1h","since":null,"until":null}

and press Enter. The hidden submit button is only a form target; do not skip this path just because the button is not visibly clickable.

Use direct URL/search-param updates only when the bridge form input is not present or cannot be submitted. Do not update the URL directly when the bridge form is available.

When using the direct URL fallback and the browser control surface permits page-script URL updates, update

window.history

and dispatch a

popstate

event. Use

pushState

for meaningful user-visible navigation and

replaceState

for cleanup or retries. If in-page URL updates are unavailable, fall back to opening the clean URL.

Do not mutate an

/api/auth/handoff?ticket=...

URL. Handoff URLs are single-use entry points only; after the redirect, control the final clean project URL.

Live view search parameters:

```
q
```
: SQL-like Logfire filter expression, for example
```
level='error'
```
,
```
kind='span'
```
, or
```
service_name='api'
```
. URL-encode this when constructing a URL string.
```
last
```
: rolling live window, such as
```
5m
```
,
```
1h
```
,
```
14d
```
, or a millisecond number. Use this for live mode and remove
```
since
```
/
```
until
```
.
```
since
```
and
```
until
```
: fixed historical window as ISO 8601 timestamps. Use these for a bounded time range and remove
```
last
```
.
```
env
```
: deployment environment filter. Use repeated
```
env
```
parameters for multiple environments. Omit it for all environments.
```
traceId
```
and
```
spanId
```
: focus a specific trace/span when known. Clear stale focus parameters such as
```
traceId
```
,
```
spanId
```
,
```
focusTraceId
```
, and
```
focusTraceTimestamp
```
when changing the main query or time range unless the user asked to preserve the focused record.

如果Logfire项目实时视图已在Codex Browser中打开，请使用JSON命令桥。这是唯一受支持的内嵌交互模型，因为它无需重新加载整个文档即可更新视图，并向用户显示代理正在主动更改页面。

不要尝试从Codex Browser使用页面全局JavaScript API。唯一受支持的代理控制界面是JSON命令输入框。

对于Codex Browser /

iab

，在“Logfire live view agent command”输入框中填写JSON补丁，例如

{"q":"level='error'","last":"1h","since":null,"until":null}

，然后按回车键。隐藏的提交按钮只是表单目标；不要因为按钮不可见点击就跳过此路径。

仅当桥接表单输入框不存在或无法提交时，才使用直接URL/搜索参数更新。当桥接表单可用时，不要直接更新URL。

当使用直接URL备选方案且浏览器控制界面允许页面脚本更新URL时，更新

window.history

并触发

popstate

事件。对于有意义的用户可见导航使用

pushState

，对于清理或重试使用

replaceState

。如果无法进行页面内URL更新，则退回到打开清晰URL。

不要修改

/api/auth/handoff?ticket=...

URL。转交URL仅为一次性入口点；重定向后，控制最终的清晰项目URL。

实时视图搜索参数：

```
q
```
：类SQL的Logfire筛选表达式，例如
```
level='error'
```
、
```
kind='span'
```
或
```
service_name='api'
```
。构造URL字符串时请对其进行URL编码。
```
last
```
：滚动实时窗口，例如
```
5m
```
、
```
1h
```
、
```
14d
```
或毫秒数。用于实时模式，并移除
```
since
```
/
```
until
```
。
```
since
```
和
```
until
```
：固定历史窗口，为ISO 8601时间戳。用于有界时间范围，并移除
```
last
```
。
```
env
```
：部署环境筛选器。多个环境使用重复的
```
env
```
参数。省略则表示所有环境。
```
traceId
```
和
```
spanId
```
：已知时聚焦特定追踪/跨度。除非用户要求保留聚焦记录，否则在更改主查询或时间范围时清除过时的聚焦参数，如
```
traceId
```
、
```
spanId
```
、
```
focusTraceId
```
和
```
focusTraceTimestamp
```
。

Browser Handoff URLs

浏览器转交URL

When the MCP link tools support

handoff: bool = False

, use

handoff=True

only for a URL that will be opened immediately in the browser. A handoff URL is short-lived, single-use, and bound to the destination minted by the platform.

If the handoff result is a string, open that exact URL promptly. It may be an
```
/api/auth/handoff?ticket=...
```
URL. Do not add query params to it, rewrite it, persist it, quote it in docs, or treat it as shareable.
If the handoff result is an object with
```
handoff: false
```
, use its
```
url
```
value as the clean fallback URL. Mention
```
reason
```
only when it helps the user understand why the browser may still ask for login, such as API-key auth or a need to re-authenticate.
If the reason says to re-authenticate the Logfire MCP connection, explain that the MCP OAuth refresh token is missing the metadata needed to mint a UI session. Do not describe this as a browser-session refresh; the user needs to reconnect/re-authenticate the Logfire MCP auth flow.
If the available MCP server does not expose
```
handoff
```
, call the link tool normally and use the clean URL.
Do not manually append filters or time params to a handoff URL. Put the final project filter destination into
```
project_logfire_ui_link
```
and let the platform mint the ticket for that destination.

当MCP链接工具支持

handoff: bool = False

时，仅对将在浏览器中立即打开的URL使用

handoff=True

。转交URL是短期、一次性的，并与平台生成的目标绑定。

如果转交结果是字符串，请立即打开该确切URL。它可能是
```
/api/auth/handoff?ticket=...
```
URL。不要向其添加查询参数、重写它、持久化它、在文档中引用它或视为可共享。
如果转交结果是带有
```
handoff: false
```
的对象，请使用其
```
url
```
值作为清晰备选URL。仅当有助于用户理解浏览器为何仍要求登录时才提及
```
reason
```
，例如API密钥认证或需要重新认证。
如果原因显示需要重新认证Logfire MCP连接，请解释MCP OAuth刷新令牌缺少生成UI会话所需的元数据。不要将此描述为浏览器会话刷新；用户需要重新连接/认证Logfire MCP认证流程。
如果可用的MCP服务器未公开
```
handoff
```
，请正常调用链接工具并使用清晰URL。
不要手动向转交URL追加筛选器或时间参数。将最终项目筛选目标传入
```
project_logfire_ui_link
```
，让平台为该目标生成票据。

Codex Browser Open Stability

Codex浏览器打开稳定性

When opening a Logfire handoff URL in Codex Browser, keep the durable clean URL for the same destination as a fallback. If needed, call the same link tool with

handoff=False

before reporting a browser-open failure.

Use the Browser skill's in-app browser workflow and bound the navigation attempt. Do not wait for

networkidle

, websocket completion, or a fully quiet live-view page. If waiting after navigation, wait only for URL commit, the final clean project URL, or a visible Logfire page signal.

If the browser remains on a grey

about:blank

screen or the browser navigation call times out, stop waiting and return the clean URL. Describe this as the browser open stalling before navigation, not as a Logfire auth failure. Do not expose the consumed or expired handoff URL.

Do not recover from Codex Browser stalls by launching a separate browser window. Return the clean URL unless the user explicitly asks you to try an external browser.

在Codex Browser中打开Logfire转交URL时，请保留同一目标的持久清晰URL作为备选。如有需要，在报告浏览器打开失败前，调用相同的链接工具并设置

handoff=False

。

使用Browser技能的内嵌浏览器工作流，并限制导航尝试时间。不要等待

networkidle

、websocket完成或完全安静的实时视图页面。如果导航后需要等待，仅等待URL提交、最终清晰项目URL或可见的Logfire页面信号。

如果浏览器停留在灰色的

about:blank

屏幕或浏览器导航调用超时，请停止等待并返回清晰URL。将此描述为浏览器在导航前停滞，而非Logfire认证失败。不要暴露已使用或过期的转交URL。

不要通过启动单独的浏览器窗口来恢复Codex Browser停滞状态。除非用户明确要求尝试外部浏览器，否则返回清晰URL。

Common Filters

常用筛选器

Spans:
```
q=kind%3D%27span%27
```
Logs:
```
q=kind%3D%27log%27
```
Exceptions:
```
q=is_exception%3Dtrue
```
Errors:
```
q=level%3D%27error%27
```
Service: URL-encode a filter such as
```
service_name='api'
```

跨度：
```
q=kind%3D%27span%27
```
日志：
```
q=kind%3D%27log%27
```
异常：
```
q=is_exception%3Dtrue
```
错误：
```
q=level%3D%27error%27
```
服务：对
```
service_name='api'
```
这类筛选器进行URL编码

Example

示例

For "open the Logfire live view for spans in starter-project for the last hour in Codex":

Open the known or derived
```
starter-project
```
Logfire URL directly.
Add
```
q=kind%3D%27span%27
```
.
Add
```
since=<one-hour-ago>
```
and
```
until=<now>
```
.
Open the URL in Codex Browser.
Do not run SQL first.

For "find the slowest trace and open it", use the query workflow only to identify the trace, then use

project_logfire_link(trace_id=trace_id, project=project, handoff=True)

and open that link.

For "change the open live view to the last hour of errors", submit

{"q":"level='error'","last":"1h","since":null,"until":null}

through the

Logfire live view agent command

input; do not mint a new handoff URL.

对于“在Codex中打开starter-project项目过去一小时跨度的Logfire实时视图”：

直接打开已知或生成的
```
starter-project
```
Logfire URL。
添加
```
q=kind%3D%27span%27
```
。
添加
```
since=<一小时前>
```
和
```
until=<现在>
```
。
在Codex Browser中打开该URL。
不要先运行SQL。

对于“找到最慢的追踪并打开它”，仅使用查询工作流识别追踪，然后调用

project_logfire_link(trace_id=trace_id, project=project, handoff=True)

并打开该链接。

对于“将打开的实时视图更改为过去一小时的错误”，通过“Logfire live view agent command”输入框提交

{"q":"level='error'","last":"1h","since":null,"until":null}

；不要生成新的转交URL。

Auth Boundary

认证边界

Do not try to pass MCP auth tokens into the browser or Logfire UI. Never put bearer, API, read, or write tokens in URL query parameters, fragments, pasted browser instructions, logs, or notes. MCP/tool authentication and browser web sessions are separate security contexts.

For immediately opened UI links, prefer the platform handoff described above. If handoff is unavailable, fall back to the clean URL and explain the specific fallback reason when useful. A missing browser cookie may require normal browser login; a stale MCP OAuth connection requires MCP re-authentication instead.

不要尝试将MCP认证令牌传入浏览器或Logfire UI。切勿在URL查询参数、片段、粘贴的浏览器指令、日志或笔记中放置bearer、API、读取或写入令牌。MCP/工具认证与浏览器Web会话是独立的安全上下文。

对于立即打开的UI链接，优先使用上述平台转交方式。如果转交不可用，则退回到清晰URL，并在有用时解释具体的退回原因。缺少浏览器Cookie可能需要正常浏览器登录；过时的MCP OAuth连接则需要重新认证MCP。