The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: focus Logs on the unified view and export queryable fields (#50073)
Saxon Fletcher232ce7e68cf5
diff --git a/apps/docs/components/SharedData.tsx b/apps/docs/components/SharedData.tsxindex 744be85b829..9e91e59cedb 100644--- a/apps/docs/components/SharedData.tsx+++ b/apps/docs/components/SharedData.tsx@@ -1,11 +1,11 @@import { ReactNode } from 'react'import { config, logConstants } from 'shared-data'-import { resolveSharedDataPath } from './SharedData.utils'+import { getLogFieldReference, resolveSharedDataPath } from './SharedData.utils'const sharedData = {config,- logConstants,+ logConstants: { schemas: getLogFieldReference(logConstants.schemas) },}/**diff --git a/apps/docs/components/SharedData.utils.test.ts b/apps/docs/components/SharedData.utils.test.tsnew file mode 100644index 00000000000..5bc8bcc86bc--- /dev/null+++ b/apps/docs/components/SharedData.utils.test.ts@@ -0,0 +1,39 @@+import { describe, expect, it } from 'vitest'++import { getLogFieldReference } from './SharedData.utils'++describe('getLogFieldReference', () => {+ it('distinguishes ClickHouse columns from both prefixed and unprefixed attributes', () => {+ const source = {+ name: 'API Gateway',+ reference: 'edge_logs',+ fields: [+ { path: 'id', type: 'string' },+ { path: 'identifier', type: 'string' },+ { path: 'metadata.response.status_code', type: 'number' },+ ],+ }+ const [result] = getLogFieldReference([source])+ expect(result.reference).toBe('edge_logs')+ expect(result.fields).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ path: 'id', queryField: 'id', queryType: 'String' }),+ expect.objectContaining({ path: 'identifier', queryField: "log_attributes['identifier']" }),+ expect.objectContaining({+ path: 'metadata.response.status_code',+ type: 'number',+ queryField: "log_attributes['response.status_code']",+ queryType: 'String',+ }),+ expect.objectContaining({+ path: 'timestamp',+ queryField: 'timestamp',+ queryType: 'DateTime64',+ }),+ expect.objectContaining({ path: 'source', queryField: 'source' }),+ ])+ )+ expect(result.fields.filter((field) => field.path === 'id')).toHaveLength(1)+ expect(source.fields).toHaveLength(3)+ })+})diff --git a/apps/docs/components/SharedData.utils.ts b/apps/docs/components/SharedData.utils.tsindex 512eab59cfe..c0fbbff1fc1 100644--- a/apps/docs/components/SharedData.utils.ts+++ b/apps/docs/components/SharedData.utils.ts@@ -17,3 +17,43 @@ export function resolveSharedDataPath(dataset: unknown, path: string): string |}return selected}++type LogSourceSchema = {+ name: string+ reference: string+ fields: { path: string; type: string }[]+}++const LOG_COLUMNS = new Map([+ ['id', 'String'],+ ['timestamp', 'DateTime64'],+ ['event_message', 'String'],+ ['severity_text', 'String'],+ ['source', 'String'],+])++/** One field mapping for the HTML reference and its Markdown export. */+export function getLogFieldReference(schemas: LogSourceSchema[]) {+ return schemas.map((schema) => {+ const fields = [...schema.fields]+ for (const [path, type] of LOG_COLUMNS) {+ if (!fields.some((field) => field.path === path)) fields.push({ path, type })+ }+ return {+ ...schema,+ fields: fields+ .sort((a, b) => a.path.localeCompare(b.path))+ .map((field) => {+ const key = field.path+ .replace(/^metadata\./, '')+ .replace(/\\/g, '\\\\')+ .replace(/'/g, "''")+ return {+ ...field,+ queryField: LOG_COLUMNS.has(field.path) ? field.path : `log_attributes['${key}']`,+ queryType: LOG_COLUMNS.get(field.path) ?? 'String',+ }+ }),+ }+ })+}diff --git a/apps/docs/content/guides/observability/log-field-reference.mdx b/apps/docs/content/guides/observability/log-field-reference.mdxindex 23bec25e0eb..99e444585ef 100644--- a/apps/docs/content/guides/observability/log-field-reference.mdx+++ b/apps/docs/content/guides/observability/log-field-reference.mdx@@ -1,42 +1,68 @@---id: 'logs-field-reference'title: 'Logs field reference'-description: 'Supabase Logs field reference'+description: 'Log sources, ClickHouse fields, and event capture limits'----Use this reference to find the fields available for each log source. Query `id`, `timestamp`, `event_message`, and `source` as top-level columns. Other structured fields are keys in the `log_attributes` map: drop the `metadata.` prefix shown in the source schema and keep the rest of the dotted path.+Each event is a row in the ClickHouse `logs` table. Filter the `source` column to select a service. The tables below list its fields; a field is not necessarily populated on every event.-For example, the schema path `metadata.request.cf.country` is queried as `log_attributes['request.cf.country']`. See [Query and filter logs](/docs/guides/observability/advanced-log-filtering) for complete ClickHouse examples.+`id`, `timestamp`, `event_message`, `severity_text`, and `source` are top-level columns. Service fields are string values in `log_attributes`, even when the original event contains a number or boolean. Use the **ClickHouse query field** column directly. See [Query logs with SQL](/docs/guides/observability/advanced-log-filtering) for casting and field discovery.++## Capture limits++- Hosted Postgres events longer than 100,000 characters and Edge Function log messages longer than 10,000 characters are truncated.+- Internal Supabase service connection events are not recorded in hosted Postgres logs.+- An Edge Function invocation uses `function_edge_logs`; its console output uses `function_logs`.+- For [API Load Balancer](/docs/guides/platform/read-replicas#api-load-balancer) traffic, `log_attributes['load_balancer_redirect_identifier']` identifies the upstream database.++## Fields by source<SharedData data="logConstants">{(logConstants) => (<Tabs scrollable size="small" type="underlined" defaultActiveId="edge_logs" queryGroup="source">{logConstants.schemas.map((schema) => (<TabPanel id={schema.reference} key={schema.reference} label={schema.name}>- <Table>- <thead>- <tr>- <th className="font-bold">Schema path</th>- <th className="font-bold">ClickHouse query field</th>- <th className="font-bold">Type</th>- </tr>- </thead>- <tbody>- {schema.fields- .sort((a, b) => a.path.localeCompare(b.path))- .map((field) => (- <tr key={field.path}>- <td className="font-mono">{field.path}</td>- <td className="font-mono">- {field.path.startsWith('metadata.')- ? `log_attributes['${field.path.slice('metadata.'.length)}']`- : field.path}- </td>- <td className="font-mono">{field.type}</td>- </tr>- ))}- </tbody>- </Table>+ <p>+ Source: <code>{schema.reference}</code>+ </p>+ <div className="border rounded-md divide-y overflow-hidden">+ {schema.fields+ .sort((a, b) => a.path.localeCompare(b.path))+ .map((field) => {+ const shortName = field.path.replace(/^metadata\./, '')+ const isTopLevel = field.queryField === field.path+ return (+ <div key={field.path} className="px-4 py-3">+ <div className="flex items-center gap-2 flex-wrap">+ <code className="text-sm">{shortName}</code>+ <span className="text-xs font-mono text-foreground-lighter bg-surface-200 px-1.5 py-0.5 rounded">+ {field.type}+ </span>+ </div>+ {!isTopLevel && (+ <div className="mt-2 flex flex-col gap-1">+ <div className="flex items-baseline gap-2">+ <span className="text-[10px] font-medium uppercase tracking-wide text-foreground-lighter border rounded px-1.5 py-px shrink-0">+ schema+ </span>+ <code className="text-xs text-foreground-lighter break-all">+ {field.path}+ </code>+ </div>+ <div className="flex items-baseline gap-2">+ <span className="text-[10px] font-medium uppercase tracking-wide text-foreground-lighter border rounded px-1.5 py-px shrink-0">+ clickhouse+ </span>+ <code className="text-xs text-foreground-lighter break-all">+ {field.queryField}+ </code>+ </div>+ </div>+ )}+ </div>+ )+ })}+ </div></TabPanel>))}</Tabs>diff --git a/apps/docs/content/guides/observability/logs.mdx b/apps/docs/content/guides/observability/logs.mdxindex 6d8b9f62278..28e03353b82 100644--- a/apps/docs/content/guides/observability/logs.mdx+++ b/apps/docs/content/guides/observability/logs.mdx@@ -1,81 +1,68 @@---id: 'logs'-title: 'Logs'-description: 'Inspect project log events in the unified Logs view in Studio'+title: 'Logs in Studio'+description: 'Filter, inspect, and export project events in the Logs view'----This guide explains how to inspect project logs in Studio. Log retention is based on your [project's pricing plan](/pricing). For details on how Logs usage is billed, see [Manage Logs usage](/docs/guides/platform/manage-your-usage/logs).+Use [Logs](/dashboard/project/_/logs) to inspect events across your hosted project's services. For SQL queries through [Explorer](/dashboard/project/_/explorer), MCP, or the API, see [Query logs with SQL](/docs/guides/observability/advanced-log-filtering).-Use this page to filter and inspect events in [Logs](#product-logs). To query the same data with SQL from Studio, MCP, the API, or a script, or to record extra Postgres, API, and Realtime events, see [Query and filter logs](/docs/guides/observability/advanced-log-filtering).+## Find events [#product-logs]-<Admonition type="note">--If you already have a specific error, start at [Diagnosing](/docs/guides/troubleshooting). To pick up a signal from these events, see [Detecting](/docs/guides/observability/detecting).--</Admonition>--## Filter and inspect events [#product-logs]--Open [Logs](/dashboard/project/_/logs). The page shows a timeline of success, warning, and error events, a filterable table, and a detail panel when you select a row.--If you don't select a log type, Logs queries **Postgres** and **API Gateway** events. Selecting log types replaces that default set.--<Admonition type="note">+1. Open [Logs](/dashboard/project/_/logs).+2. Set the **Time Range** in the sidebar, or select a range on the timeline.+3. Select one or more **Log Type** values.+4. Add filters in the filter bar, or type text to search event messages.+5. Select a row to inspect the event.-For regular expression filtering, structured-field queries, and field discovery, see [Query and filter logs](/docs/guides/observability/advanced-log-filtering).+Without a log type selection, Logs queries **Postgres** and **API Gateway**. Selecting types replaces this default set. The timeline groups events by success, warning, and error.-</Admonition>+## Filter events-### Filter logs+{/* supa-mdx-lint-disable Rule003Spelling */}+| Filter | Behavior |+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Log Type | Select API Gateway, Postgres, Auth, Storage, PostgREST, Edge Function, Realtime, or pooler events. |+| Level | Match success, warning, or error. |+| Status | Match an HTTP status or Postgres SQLSTATE. |+| Method | Match an HTTP method. |+| Pathname | Match a request path. |+| Event message | Use **iLike** or **Not iLike** for case-insensitive text matching or exclusion. Plain text matches anywhere in the message; `%` specifies a wildcard pattern. |+| User | Match the user's ID in Auth actor IDs or API Gateway JWT subjects. Other log types cannot match this filter. |-1. Open [Logs](/dashboard/project/_/logs).-2. Set the **Time Range** in the sidebar.-3. Select one or more **Log Type** values. Nested toggles under API Gateway include or exclude Auth, Storage, and PostgREST request paths. The nested toggle under Postgres shows or hides connection logs.-4. Optionally filter by **Level**, **Status**, **Method**, **Pathname**, or **Event message**. Type in the filter bar to search event messages.-5. Optionally filter by **User**. This filter only matches Auth and Postgres events.+{/* supa-mdx-lint-enable Rule003Spelling */}-Refresh the table, hide columns, download matching rows as CSV or JSON, or turn on live mode to stream new events.+Filters other than **Event message** and **User** support **Equals** and **Not equal**. **User** supports **Equals**. Included values within a field match any selected value; exclusions remove every selected value. Filters on different fields must all match.-### Log types+### Gateway and service logs-Selecting a log type in Studio queries the matching ClickHouse `source`. For the `source` names to use in SQL, see [Sources](/docs/guides/observability/advanced-log-filtering#logs-explorer).+The nested service toggles under **API Gateway** include or exclude gateway request paths. Selecting the separate **Auth**, **Storage**, or **PostgREST** log type retrieves that service's own logs. These are different events.-| Log type | Events |-| ------------- | ----------------------------------------------------------------- |-| API Gateway | HTTP requests through the API gateway, including REST and GraphQL |-| Postgres | Database queries and activity |-| PostgREST | PostgREST server logs |-| Auth | Auth server logs |-| Storage | Storage API server logs |-| Edge Function | Edge Function HTTP invocations and `console` output |-| Realtime | Realtime server logs |-| Supavisor | Connection pooler logs |-| PgBouncer | PgBouncer logs |--Selecting **API Gateway** is not the same as selecting **Auth**, **Storage**, or **PostgREST**. The nested API Gateway toggles filter HTTP paths on the gateway. The Auth, Storage, and PostgREST log types query those services' own logs.+For SQL source names, see the [Log field reference](/docs/guides/observability/log-field-reference).### Postgres [#postgres]-Postgres logs show queries and activity for your database. Connection lifecycle events appear here when [connection logging](/docs/guides/observability/advanced-log-filtering#logging-postgres-connections) is enabled. They are included by default; clear **Connection logs** under the Postgres log type to hide them.+Postgres logs contain database activity and errors. Connection events appear when [connection logging](/docs/guides/platform/postgres-connection-logging) is enabled. Clear **Connection logs** under **Postgres** to hide them.To record additional statement classes, see [Logging Postgres queries](/docs/guides/observability/advanced-log-filtering#logging-postgres-queries).-### Inspect a log+## Inspect an event [#expanding-results]++Select a row to open its detail panel. **Overview**, when available for the log type, shows service details. **Raw JSON** shows the event data. Dock the panel at the bottom or on the right.-1. Select a row in the table.-2. Open **Overview** to follow the request through the services that handled it. Open **Raw JSON** for the full event.-3. Dock the panel at the bottom or on the right.+Edge Function invocations can include associated console output. In SQL, invocation events use `function_edge_logs` and console events use `function_logs`.-Edge Function rows include console output from that invocation. In SQL, the HTTP request is `function_edge_logs` and console output is `function_logs`. Function log messages longer than 10,000 characters are truncated.+## Watch, share, and export-### Expanding results [#expanding-results]+- Select **Live** to fetch new events automatically. Select it again to pause. Starting live mode clears the fixed time range and sort; selecting a time range or sort stops live mode.+- Copy the page URL to share the current filters. Recipients need access to the project.+- Open **Download logs**, choose CSV or JSON, and select a result limit of 100, 500, or 1,000 rows. The export applies the current filters. Without a fixed time range, choose the duration to retrieve.-In the [Logs Explorer](/dashboard/project/_/logs/explorer), query results can be hard to read in the table. Double-click a row to expand it as JSON:+For continuous export, use [Log drains](/docs/guides/observability/log-drains).-+## Missing results [#single-service-collections]-### Single-service collections [#single-service-collections]+Check the time range, selected log types, and exclusions first. **User** combined with only Postgres or another unsupported type returns no matches. An empty result does not establish that the user had no activity.-The Logs sidebar still lists collections for one service at a time, such as [API Gateway](/dashboard/project/_/logs/edge-logs) or [Postgres](/dashboard/project/_/logs/postgres-logs). Use a collection when you want a dedicated view.+Events must be recorded before they can appear in Logs. See [Logging configuration](/docs/guides/observability/advanced-log-filtering#logging-postgres-connections) and the [source limitations](/docs/guides/observability/log-field-reference#capture-limits).-If [Read Replicas](/docs/guides/platform/read-replicas) are enabled, collections can filter by database with the **Source** control. For API logs from the [API Load Balancer](/docs/guides/platform/read-replicas#api-load-balancer), the upstream database is the Redirect Identifier field (`log_attributes['load_balancer_redirect_identifier']` in SQL).+Retention depends on your [pricing plan](/pricing). See [Manage Logs usage](/docs/guides/platform/manage-your-usage/logs) for billing details.diff --git a/apps/docs/internals/markdown-schema/SharedData.ts b/apps/docs/internals/markdown-schema/SharedData.tsindex c915f95d7c2..430b6740246 100644--- a/apps/docs/internals/markdown-schema/SharedData.ts+++ b/apps/docs/internals/markdown-schema/SharedData.ts@@ -1,25 +1,29 @@import { createRequire } from 'node:module'-import { resolveSharedDataPath } from '../../components/SharedData.utils'+import { getLogFieldReference, resolveSharedDataPath } from '../../components/SharedData.utils'// tsx's ESM loader can't pick up named exports from the `shared-data` package// (CJS, no `"type": "module"`). Load via `createRequire` to use CJS interop —// this file only runs in the build script, never in the Next.js bundle.const { config, logConstants } = createRequire(import.meta.url)('shared-data')-type Field = { path: string; type: string }-type Schema = { name: string; fields: Field[] }-const sharedData: Record<string, unknown> = { config, logConstants }-const renderLogConstants = (data: { schemas: Schema[] }): string =>- data.schemas- .map(- (s) =>- `#### ${s.name}\n${[...s.fields]- .sort((a, b) => a.path.localeCompare(b.path))- .map((f) => ` - \`${f.path}\`, \`${f.type}\``)- .join('\n')}`+const renderLogConstants = (data: typeof logConstants): string =>+ getLogFieldReference(data.schemas)+ .map((schema) =>+ [+ `### ${schema.name}`,+ '',+ `Source: \`${schema.reference}\``,+ '',+ '| Schema path | ClickHouse query field | Source type | Query value type |',+ '| --- | --- | --- | --- |',+ ...schema.fields.map(+ (field) =>+ `| \`${field.path}\` | \`${field.queryField}\` | \`${field.type}\` | \`${field.queryType}\` |`+ ),+ ].join('\n')).join('\n\n')@@ -41,6 +45,6 @@ export const SharedData = ({// The schema walker strips the MDX expression children before this handler// runs, and we can't evaluate the function statically anyway — hardcode the// markdown for the only dataset that uses this form today.- if (props.data === 'logConstants') return renderLogConstants(dataset as { schemas: Schema[] })+ if (props.data === 'logConstants') return renderLogConstants(dataset as typeof logConstants)return ''}diff --git a/apps/studio/components/interfaces/UnifiedLogs/UnifiedLogs.queries.ts b/apps/studio/components/interfaces/UnifiedLogs/UnifiedLogs.queries.tsindex 973e24e75b3..777a6e49ba3 100644--- a/apps/studio/components/interfaces/UnifiedLogs/UnifiedLogs.queries.ts+++ b/apps/studio/components/interfaces/UnifiedLogs/UnifiedLogs.queries.ts@@ -357,14 +357,8 @@ const userFilterValue = (search: QuerySearchParamsType): string =>typeof search.user === 'string' ? search.user.trim() : ''/**- * Cross-cutting "attributable to one user" condition. Only the two sources that can- * be positively tied to a user are eligible, each with its own match:- * - auth_logs: structured identity (`auth_event.actor_id`)- * - postgres_logs: the identifier appears verbatim in the error text (e.g. a 23502- * failing row echoing the id column).- * edge_logs / storage_logs / realtime_logs carry no per-user field and can't satisfy- * either branch, so they're auto-excluded while the filter is active — never guessed- * at via IP or timestamp proximity.+ * Matches structured user identifiers in Auth events and API Gateway JWT subjects.+ * Sources without these fields cannot match the user filter.*/const userAttributionCondition = (search: QuerySearchParamsType): SafeLogSqlFragment | null => {const value = userFilterValue(search)@@ -381,12 +375,10 @@ const USER_ATTRIBUTABLE_SOURCES = new Set([LOG_TYPE_TO_SOURCE.auth, LOG_TYPE_TO_/*** True when the user filter is active but an explicit log_type filter restricts the- * view to source(s) that can never satisfy `userAttributionCondition` (e.g. `edge`) —+ * view to source(s) that can never satisfy `userAttributionCondition` (e.g. `postgres`) —* the combination is guaranteed to match zero rows. Consumed by the UI to show a* specific empty state instead of the generic "No results found".*- * [Joshen] Basically filtering by user only works on Auth and Postgres logs atm- * Refer to userAttributeCondition above*/export const isUserFilterUnreachable = (search: QuerySearchParamsType): boolean => {if (!userFilterValue(search)) return falsediff --git a/apps/studio/components/interfaces/UnifiedLogs/UnifiedLogs.tsx b/apps/studio/components/interfaces/UnifiedLogs/UnifiedLogs.tsxindex 06724b70d65..f67b3f1040a 100644--- a/apps/studio/components/interfaces/UnifiedLogs/UnifiedLogs.tsx+++ b/apps/studio/components/interfaces/UnifiedLogs/UnifiedLogs.tsx@@ -521,7 +521,7 @@ export const UnifiedLogs = () => {<div className="text-sm flex flex-col gap-y-1"><p className="text-foreground-light">No results found</p><p className="text-foreground-lighter">- Filtering by user is only supported for Auth and Postgres log types+ Filtering by user is only supported for Auth and API Gateway log types</p></div>) : undefined