Feat/apps observability by qingniaotonghua · Pull Request #1583 · larksuite/cli

qingniaotonghua · 2026-06-25T13:21:28Z

Summary

Adds first-class apps environment-variable management and observability shortcuts, aligning command naming and environment flags with common CLI conventions. The change introduces logs, traces, metrics, analytics, and env workflows for Miaoda/Spark apps, with updated skill guidance and focused tests for request shape, output schema, and error handling.

Changes

Add apps observability shortcuts for logs, traces, metrics, and analytics, including shared environment validation, output schemas, dry-run coverage, and OpenAPI request mapping.
Add apps env commands using env naming (+env-list, +env-set, +env-delete) and update +env-pull behavior to use the POST env-vars API.
Standardize user-facing environment flags on --environment only; remove --env usage and do not expose -e shorthand.
Add source-map stack reverse lookup for +log-get, exposing source_stack for applicable frontend error logs.
Improve apps error hints and output behavior around env operations, log detail, metric/analytics query formatting, and JSON/pretty output contracts.
Update lark-apps skill docs for env, env-pull, and observability, including OpenAPI environment mapping and source stack guidance.
Add/rename dry-run E2E and skill-eval coverage for apps env and observability flows.

Test Plan

Unit tests pass: PATH=/usr/local/go/bin:$PATH go test ./shortcuts/apps -count=1

Build passes: PATH=/usr/local/go/bin:$PATH make build

Manual local verification confirms the lark-cli apps env and observability flows work as expected against the proxy/dev test environment

Related Issues

None

Summary by CodeRabbit

New Features
- Added app environment shortcuts to list, set, delete, and pull variables.
- Added new observability shortcuts for logs, traces, metrics, and analytics.
Bug Fixes
- Improved handling of different API response shapes for environment, log, trace, and metric data.
- Made output more consistent, including cleaner tables, normalized fields, and safer redaction of secret values.
Documentation
- Updated app shortcut guidance and examples to reflect the new commands and usage rules.
Tests
- Expanded coverage for request validation, dry-run behavior, output formatting, and safety checks.

CLAassistant · 2026-06-25T13:21:35Z

All committers have signed the CLA.

coderabbitai · 2026-06-25T13:21:45Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ff18cad6-5bc0-4d14-8ac8-83b36b4adcbb

📥 Commits

Reviewing files that changed from the base of the PR and between 806e867 and 9efa8b3.

📒 Files selected for processing (24)

shortcuts/apps/apps_env.go
shortcuts/apps/apps_env_pull.go
shortcuts/apps/apps_env_pull_test.go
shortcuts/apps/apps_env_test.go
shortcuts/apps/apps_examples_test.go
shortcuts/apps/apps_hints_test.go
shortcuts/apps/apps_observability_common.go
shortcuts/apps/apps_observability_common_test.go
shortcuts/apps/apps_observability_logs.go
shortcuts/apps/apps_observability_logs_test.go
shortcuts/apps/apps_observability_metrics.go
shortcuts/apps/apps_observability_metrics_test.go
shortcuts/apps/apps_observability_traces.go
shortcuts/apps/apps_observability_traces_test.go
shortcuts/apps/apps_output_schema.go
shortcuts/apps/apps_output_schema_test.go
shortcuts/apps/shortcuts.go
shortcuts/apps/shortcuts_test.go
skills/lark-apps/SKILL.md
skills/lark-apps/references/lark-apps-env-pull.md
skills/lark-apps/references/lark-apps-env.md
skills/lark-apps/references/lark-apps-observability.md
tests/cli_e2e/apps/apps_env_pull_dryrun_test.go
tests_e2e/apps/2026_06_23_apps_observability_envvar_test.go

📝 Walkthrough

Walkthrough

Adds env-var management shortcuts, updates env-pull request/response handling, introduces observability log/trace/metric/analytics shortcuts, and adds shared output-schema and validation helpers with expanded tests, docs, registry tips, and e2e coverage.

Changes

Apps command expansion

Layer / File(s)	Summary
Schema projection and table rendering `shortcuts/apps/apps_output_schema.go`, `shortcuts/apps/apps_output_schema_test.go`	`appsOutputSchema` projects declared columns, formats time and duration cells, and renders ASCII tables from normalized rows.
Shared registry, docs, and contract tests `shortcuts/apps/shortcuts.go`, `shortcuts/apps/shortcuts_test.go`, `shortcuts/apps/examples_test.go`, `skills/lark-apps/SKILL.md`, `skills/lark-apps/references/.md`, `tests_e2e/apps/2026_06_23_apps_observability_envvar_test.go`	Shortcut tips, canonical-command checks, command references, and e2e contract coverage are updated for env and observability commands.
Env variable shortcuts `shortcuts/apps/apps_env.go`, `shortcuts/apps/apps_env_test.go`, `tests_e2e/apps/2026_06_23_apps_observability_envvar_test.go`	`+env-list`, `+env-set`, and `+env-delete` add env selection, key validation, request building, response normalization, and output formatting.
Env pull request shape `shortcuts/apps/apps_env_pull.go`, `shortcuts/apps/apps_env_pull_test.go`, `shortcuts/apps/apps_hints_test.go`, `tests/cli_e2e/apps/apps_env_pull_dryrun_test.go`	`+env-pull` now sends a fixed dev request body, accepts alternate response fields, and has updated request-body and hint assertions.
Log search and detail shortcuts `shortcuts/apps/apps_observability_logs.go`, `shortcuts/apps/apps_observability_logs_test.go`	`+log-list` and `+log-get` add filter construction, response normalization, source-stack resolution, and formatting checks.
Trace search and detail shortcuts `shortcuts/apps/apps_observability_traces.go`, `shortcuts/apps/apps_observability_traces_test.go`	`+trace-list` and `+trace-get` add trace aggregation, alias normalization, and detail/table rendering with tests.
Metric and analytics queries `shortcuts/apps/apps_observability_metrics.go`, `shortcuts/apps/apps_observability_metrics_test.go`	`+metric-query` and `+analytics-query` add request shaping, series normalization, zero-filling, and output formatting with tests.

Sequence Diagram(s)

Env variable write flow

sequenceDiagram
  participant lark-cli
  participant AppsEnvVarSet
  participant CallAPITyped
  participant create_or_update_env_var
  lark-cli->>AppsEnvVarSet: +env-set --app-id ... --key ... --value ...
  AppsEnvVarSet->>CallAPITyped: POST create_or_update_env_var
  CallAPITyped->>create_or_update_env_var: env, key, value
  create_or_update_env_var-->>CallAPITyped: action
  CallAPITyped-->>AppsEnvVarSet: response map
  AppsEnvVarSet-->>lark-cli: key, env, action

Log detail flow

sequenceDiagram
  participant lark-cli
  participant AppsLogGet
  participant search_logs
  participant resolve_stack_trace
  participant appsPrintSchemaTable
  lark-cli->>AppsLogGet: +log-get --log-id ...
  AppsLogGet->>search_logs: POST search_logs limit=1
  search_logs-->>AppsLogGet: log item
  AppsLogGet->>resolve_stack_trace: resolve ERROR log source stack
  resolve_stack_trace-->>AppsLogGet: source_stack fields
  AppsLogGet->>appsPrintSchemaTable: render normalized row
  appsPrintSchemaTable-->>lark-cli: table output

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~90+ minutes

Possibly related PRs

larksuite/cli#1002: Extends the same shortcuts/apps registry surface with app shortcut additions and canonical command handling.

Suggested labels

feature

Suggested reviewers

fangshuyu-768
liangshuo-1

Poem

A bunny hopped through logs so bright,
And traced the stars in CLI light.
Env vars danced in neat little rows,
While metrics bloomed like carrots in glows.
🐰 Hop! The app garden sings tonight.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/apps-observability

⚔️ Resolve merge conflicts

Resolve merge conflict in branch feat/apps-observability

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

qingniaotonghua added 13 commits June 23, 2026 17:10

feat: add apps observability helpers

8d061ea

feat: add apps log observability shortcuts

e9fde3e

feat: add apps trace observability shortcuts

fdcd9f6

feat: add apps metric analytics shortcuts

9b9ac87

feat: add apps envvar shortcuts

736db1c

docs: document apps observability envvar shortcuts

8939bff

fix: add apps observability env hint

46c99cb

test: cover apps envvar delete dry-run

6ff02ea

fix: align apps observability OpenAPI schema

2cfe090

fix: map apps observability named series

0f88409

fix: apps observability api upgrade

0552c5c

fix: refine apps observability output

d2452b7

fix: upgrade observability and env

9efa8b3

github-actions Bot added the size/XL Architecture-level or global-impact change label Jun 25, 2026

qingniaotonghua closed this Jun 25, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feat/apps observability - #1583

Feat/apps observability#1583
qingniaotonghua wants to merge 13 commits into
mainfrom
feat/apps-observability

qingniaotonghua commented Jun 25, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

CLAassistant commented Jun 25, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 25, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

qingniaotonghua commented Jun 25, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test Plan

Related Issues

Summary by CodeRabbit

Uh oh!

CLAassistant commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

qingniaotonghua commented Jun 25, 2026 •

edited by coderabbitai Bot

Loading

CLAassistant commented Jun 25, 2026 •

edited

Loading

coderabbitai Bot commented Jun 25, 2026 •

edited

Loading