diff --git a/packages/app/src/cli/commands/app/logs.test.ts b/packages/app/src/cli/commands/app/logs.test.ts index 3a66364700c..9ca2ba4f611 100644 --- a/packages/app/src/cli/commands/app/logs.test.ts +++ b/packages/app/src/cli/commands/app/logs.test.ts @@ -61,6 +61,10 @@ test('help lists every log type with its filters, and every filter applies to a for (const {name} of logTypes) expect(Logs.description).toContain(`- ${name}: `) }) +test('help states the backend time-window limits', () => { + expect(Logs.description).toContain('Maximum: 1-day window within the last 7 days, 1000 records.') +}) + test('parses space/equals forms and forwards effective defaults', async () => { vi.mocked(retrieveLogs).mockResolvedValue(result()) await new Logs( diff --git a/packages/app/src/cli/commands/app/logs.ts b/packages/app/src/cli/commands/app/logs.ts index 6ce0dba84db..7a7158e3641 100644 --- a/packages/app/src/cli/commands/app/logs.ts +++ b/packages/app/src/cli/commands/app/logs.ts @@ -21,7 +21,7 @@ Different filters combine with AND; each accepts one exact value. Type-specific ${logTypesHelp()} -Defaults: preceding hour, 20 records. Maximum: seven-day window within thirty days, 1000 records. Time inputs accept whole seconds only. +Defaults: preceding hour, 20 records. Maximum: 1-day window within the last 7 days, 1000 records. Time inputs accept whole seconds only. --json preserves native record JSON in logs[], including fractional timestamps, diagnostic fields, bodies, and producer truncation flags.` diff --git a/packages/cli/README.md b/packages/cli/README.md index d82b782a5d1..3c4c81c6e1a 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -5783,7 +5783,7 @@ DESCRIPTION - sidekick: Sidekick events. Filters: --status, --target. - ui-extension: UI extension errors. Filters: --status, --target. - Defaults: preceding hour, 20 records. Maximum: seven-day window within thirty days, 1000 records. Time inputs accept + Defaults: preceding hour, 20 records. Maximum: 1-day window within the last 7 days, 1000 records. Time inputs accept whole seconds only. --json preserves native record JSON in logs[], including fractional timestamps, diagnostic fields, bodies, and diff --git a/packages/cli/oclif.manifest.json b/packages/cli/oclif.manifest.json index 261966de9c1..87a44e5a372 100644 --- a/packages/cli/oclif.manifest.json +++ b/packages/cli/oclif.manifest.json @@ -3822,8 +3822,8 @@ "args": { }, "customPluginName": "@shopify/app", - "description": "Returns a list of historical app logs and exits. Defaults to all supported log types. Use --type to select a type; repeat it to select multiple.\n\nFast retrieval is the default: leave out --sort. Prefer this mode with a narrow time window and selective filters to consume less throttle capacity. The CLI orders the returned records oldest first, but when the limit is reached they aren't necessarily the oldest or newest matches.\n\nUse server-side sorting only when selecting the oldest or newest matching records matters: --sort timestamp selects oldest first; add --order desc for newest first. This sorts before the result limit and is subject to API query limits.\n\nWhen fewer than --limit records are returned, all matching records available at query time were returned. Sorting isn't needed to establish completeness.\n\nDifferent filters combine with AND; each accepts one exact value. Type-specific filters exclude records without that field; combining --topic and --operation-name returns no records.\n\nLog types and the filters that apply to each. Every type also accepts --store.\n\n- webhook: Webhook deliveries. Filters: --status, --topic, --status-code.\n- graphql: GraphQL API requests. Filters: --status, --operation-type, --operation-name, --request-id.\n- function: Shopify Function runs. Filters: --status, --function-handle, --target.\n- app-event: Events the app sent with the App Events API. Filters: --event-handle.\n- app-billing-event: Billing outcomes of app events. Filters: --status, --event-handle.\n- rest: REST API requests. Filters: --status, --status-code, --request-id, --method, --request-path.\n- sidekick: Sidekick events. Filters: --status, --target.\n- ui-extension: UI extension errors. Filters: --status, --target.\n\nDefaults: preceding hour, 20 records. Maximum: seven-day window within thirty days, 1000 records. Time inputs accept whole seconds only.\n\n--json preserves native record JSON in logs[], including fractional timestamps, diagnostic fields, bodies, and producer truncation flags.\n\nUse `--json-schema` to print the result, error, and event schemas.\n\nOutput from `--json` conforms to the `HistoricalAppLogs` schema.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"logs\": {\n \"type\": \"array\",\n \"items\": {\n \"$ref\": \"#/definitions/AppLogRecord\"\n }\n },\n \"ordering\": {\n \"type\": \"string\",\n \"enum\": [\n \"subset-timestamp-asc\",\n \"timestamp-asc\",\n \"timestamp-desc\"\n ],\n \"description\": \"subset-timestamp-asc sorts only the returned subset in the CLI, not necessarily the oldest or newest matches when the limit is reached. timestamp-asc and timestamp-desc request server sorting before the limit.\"\n },\n \"limitations\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Empty when fewer than the requested limit are returned.\"\n }\n },\n \"required\": [\n \"logs\",\n \"ordering\",\n \"limitations\"\n ],\n \"additionalProperties\": false,\n \"title\": \"HistoricalAppLogs\",\n \"definitions\": {\n \"AppLogRecord\": {\n \"type\": \"object\",\n \"properties\": {\n \"timestamp\": {\n \"type\": \"string\",\n \"format\": \"date-time\",\n \"description\": \"Native API timestamp; fractional seconds are preserved.\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Native API enum, such as WEBHOOK or GRAPHQL_REQUEST.\"\n },\n \"resultStatus\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"shopMyshopifyDomain\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"timestamp\",\n \"type\",\n \"shopMyshopifyDomain\"\n ],\n \"additionalProperties\": true,\n \"description\": \"Native record JSON. All additional approved API fields are preserved without renaming or truncation.\"\n }\n },\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```", - "descriptionWithMarkdown": "Returns a list of historical app logs and exits. Defaults to all supported log types. Use --type to select a type; repeat it to select multiple.\n\nFast retrieval is the default: leave out --sort. Prefer this mode with a narrow time window and selective filters to consume less throttle capacity. The CLI orders the returned records oldest first, but when the limit is reached they aren't necessarily the oldest or newest matches.\n\nUse server-side sorting only when selecting the oldest or newest matching records matters: --sort timestamp selects oldest first; add --order desc for newest first. This sorts before the result limit and is subject to API query limits.\n\nWhen fewer than --limit records are returned, all matching records available at query time were returned. Sorting isn't needed to establish completeness.\n\nDifferent filters combine with AND; each accepts one exact value. Type-specific filters exclude records without that field; combining --topic and --operation-name returns no records.\n\nLog types and the filters that apply to each. Every type also accepts --store.\n\n- webhook: Webhook deliveries. Filters: --status, --topic, --status-code.\n- graphql: GraphQL API requests. Filters: --status, --operation-type, --operation-name, --request-id.\n- function: Shopify Function runs. Filters: --status, --function-handle, --target.\n- app-event: Events the app sent with the App Events API. Filters: --event-handle.\n- app-billing-event: Billing outcomes of app events. Filters: --status, --event-handle.\n- rest: REST API requests. Filters: --status, --status-code, --request-id, --method, --request-path.\n- sidekick: Sidekick events. Filters: --status, --target.\n- ui-extension: UI extension errors. Filters: --status, --target.\n\nDefaults: preceding hour, 20 records. Maximum: seven-day window within thirty days, 1000 records. Time inputs accept whole seconds only.\n\n--json preserves native record JSON in logs[], including fractional timestamps, diagnostic fields, bodies, and producer truncation flags.", + "description": "Returns a list of historical app logs and exits. Defaults to all supported log types. Use --type to select a type; repeat it to select multiple.\n\nFast retrieval is the default: leave out --sort. Prefer this mode with a narrow time window and selective filters to consume less throttle capacity. The CLI orders the returned records oldest first, but when the limit is reached they aren't necessarily the oldest or newest matches.\n\nUse server-side sorting only when selecting the oldest or newest matching records matters: --sort timestamp selects oldest first; add --order desc for newest first. This sorts before the result limit and is subject to API query limits.\n\nWhen fewer than --limit records are returned, all matching records available at query time were returned. Sorting isn't needed to establish completeness.\n\nDifferent filters combine with AND; each accepts one exact value. Type-specific filters exclude records without that field; combining --topic and --operation-name returns no records.\n\nLog types and the filters that apply to each. Every type also accepts --store.\n\n- webhook: Webhook deliveries. Filters: --status, --topic, --status-code.\n- graphql: GraphQL API requests. Filters: --status, --operation-type, --operation-name, --request-id.\n- function: Shopify Function runs. Filters: --status, --function-handle, --target.\n- app-event: Events the app sent with the App Events API. Filters: --event-handle.\n- app-billing-event: Billing outcomes of app events. Filters: --status, --event-handle.\n- rest: REST API requests. Filters: --status, --status-code, --request-id, --method, --request-path.\n- sidekick: Sidekick events. Filters: --status, --target.\n- ui-extension: UI extension errors. Filters: --status, --target.\n\nDefaults: preceding hour, 20 records. Maximum: 1-day window within the last 7 days, 1000 records. Time inputs accept whole seconds only.\n\n--json preserves native record JSON in logs[], including fractional timestamps, diagnostic fields, bodies, and producer truncation flags.\n\nUse `--json-schema` to print the result, error, and event schemas.\n\nOutput from `--json` conforms to the `HistoricalAppLogs` schema.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"logs\": {\n \"type\": \"array\",\n \"items\": {\n \"$ref\": \"#/definitions/AppLogRecord\"\n }\n },\n \"ordering\": {\n \"type\": \"string\",\n \"enum\": [\n \"subset-timestamp-asc\",\n \"timestamp-asc\",\n \"timestamp-desc\"\n ],\n \"description\": \"subset-timestamp-asc sorts only the returned subset in the CLI, not necessarily the oldest or newest matches when the limit is reached. timestamp-asc and timestamp-desc request server sorting before the limit.\"\n },\n \"limitations\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Empty when fewer than the requested limit are returned.\"\n }\n },\n \"required\": [\n \"logs\",\n \"ordering\",\n \"limitations\"\n ],\n \"additionalProperties\": false,\n \"title\": \"HistoricalAppLogs\",\n \"definitions\": {\n \"AppLogRecord\": {\n \"type\": \"object\",\n \"properties\": {\n \"timestamp\": {\n \"type\": \"string\",\n \"format\": \"date-time\",\n \"description\": \"Native API timestamp; fractional seconds are preserved.\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Native API enum, such as WEBHOOK or GRAPHQL_REQUEST.\"\n },\n \"resultStatus\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"shopMyshopifyDomain\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"timestamp\",\n \"type\",\n \"shopMyshopifyDomain\"\n ],\n \"additionalProperties\": true,\n \"description\": \"Native record JSON. All additional approved API fields are preserved without renaming or truncation.\"\n }\n },\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```", + "descriptionWithMarkdown": "Returns a list of historical app logs and exits. Defaults to all supported log types. Use --type to select a type; repeat it to select multiple.\n\nFast retrieval is the default: leave out --sort. Prefer this mode with a narrow time window and selective filters to consume less throttle capacity. The CLI orders the returned records oldest first, but when the limit is reached they aren't necessarily the oldest or newest matches.\n\nUse server-side sorting only when selecting the oldest or newest matching records matters: --sort timestamp selects oldest first; add --order desc for newest first. This sorts before the result limit and is subject to API query limits.\n\nWhen fewer than --limit records are returned, all matching records available at query time were returned. Sorting isn't needed to establish completeness.\n\nDifferent filters combine with AND; each accepts one exact value. Type-specific filters exclude records without that field; combining --topic and --operation-name returns no records.\n\nLog types and the filters that apply to each. Every type also accepts --store.\n\n- webhook: Webhook deliveries. Filters: --status, --topic, --status-code.\n- graphql: GraphQL API requests. Filters: --status, --operation-type, --operation-name, --request-id.\n- function: Shopify Function runs. Filters: --status, --function-handle, --target.\n- app-event: Events the app sent with the App Events API. Filters: --event-handle.\n- app-billing-event: Billing outcomes of app events. Filters: --status, --event-handle.\n- rest: REST API requests. Filters: --status, --status-code, --request-id, --method, --request-path.\n- sidekick: Sidekick events. Filters: --status, --target.\n- ui-extension: UI extension errors. Filters: --status, --target.\n\nDefaults: preceding hour, 20 records. Maximum: 1-day window within the last 7 days, 1000 records. Time inputs accept whole seconds only.\n\n--json preserves native record JSON in logs[], including fractional timestamps, diagnostic fields, bodies, and producer truncation flags.", "enableJsonFlag": false, "examples": [ "<%= config.bin %> <%= command.id %> --client-id APP_CLIENT_ID --type webhook --topic orders/create --status failure --since 30m",