Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

fix(api): profile metrics count every session and show real durations

Carl-Gerhard Lindesvärd34f188943e39
diff --git a/apps/start/src/components/profiles/profile-metrics.tsx b/apps/start/src/components/profiles/profile-metrics.tsx
index f2f560ca1..00a38d51f 100644
--- a/apps/start/src/components/profiles/profile-metrics.tsx
+++ b/apps/start/src/components/profiles/profile-metrics.tsx
@@ -1,11 +1,12 @@
import type { IProfileMetrics } from '@openpanel/core';
import { OverviewMetricCard } from '@/components/overview/overview-metric-card';
-type Props = {
+interface Props {
/** `null` when nothing is known about the profile — no row and no events. */
data: IProfileMetrics | null;
-};
+}
+// The card's 'min' unit takes seconds and renders them as a duration.
const PROFILE_METRICS = [
{
title: 'Total Events',
@@ -85,7 +86,7 @@ const PROFILE_METRICS = [
hideOnZero: false,
},
{
- title: 'Avg Time Between Sessions (h)',
+ title: 'Avg Time Between Sessions',
key: 'avgTimeBetweenSessions',
unit: 'min',
inverted: false,
diff --git a/packages/core/src/modules/mcp/src/integration/tools.test.ts b/packages/core/src/modules/mcp/src/integration/tools.test.ts
index 8574c8f5e..3636d9382 100644
--- a/packages/core/src/modules/mcp/src/integration/tools.test.ts
+++ b/packages/core/src/modules/mcp/src/integration/tools.test.ts
@@ -455,7 +455,7 @@ describe('get_profile_metrics', () => {
// No error — bug was getProfileMetrics returns single object, not array
expect(res.error).toBeUndefined();
expect(res.profileId).toBe(FIXTURE.profiles.charlie);
- expect(res.sessions).toBe(1); // 1 session_start event
+ expect(res.sessions).toBe(2); // sess-charlie-1 and sess-charlie-2 in the sessions table
expect(res.screenViews).toBe(1); // 1 screen_view event
expect(res.totalEvents).toBe(5); // session_start + screen_view + page_view + purchase + session_end
expect(res.conversionEvents).toBe(2); // page_view + purchase (excludes session_start/screen_view/session_end)
diff --git a/packages/core/src/modules/mcp/src/tools/analytics/profile-metrics.ts b/packages/core/src/modules/mcp/src/tools/analytics/profile-metrics.ts
index 0b6fb35a3..713b75406 100644
--- a/packages/core/src/modules/mcp/src/tools/analytics/profile-metrics.ts
+++ b/packages/core/src/modules/mcp/src/tools/analytics/profile-metrics.ts
@@ -1,6 +1,9 @@
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
-import { getProfileMetrics } from '../../../../profile/profile.service';
+import {
+ getProfileMetrics,
+ summarizeProfileMetrics,
+} from '../../../../profile/profile.service';
import {
type McpToolDeps,
projectIdSchema,
@@ -26,22 +29,7 @@ export function registerProfileMetricTools(
if (!raw) {
return { error: 'Profile not found or has no events', profileId };
}
- return {
- profileId,
- firstSeen: raw.firstSeen,
- lastSeen: raw.lastSeen,
- sessions: raw.sessions,
- screenViews: raw.screenViews,
- totalEvents: raw.totalEvents,
- conversionEvents: raw.conversionEvents,
- uniqueDaysActive: raw.uniqueDaysActive,
- avgSessionDurationMin: raw.durationAvg,
- p90SessionDurationMin: raw.durationP90,
- avgEventsPerSession: raw.avgEventsPerSession,
- avgTimeBetweenSessionsSec: raw.avgTimeBetweenSessions,
- bounceRate: raw.bounceRate,
- revenue: raw.revenue,
- };
+ return summarizeProfileMetrics(profileId, raw);
})
);
}
diff --git a/packages/core/src/modules/profile/profile.service.ts b/packages/core/src/modules/profile/profile.service.ts
index a5b8409c2..711cc528f 100644
--- a/packages/core/src/modules/profile/profile.service.ts
+++ b/packages/core/src/modules/profile/profile.service.ts
@@ -2,7 +2,7 @@
// `buildFilterWhere`, the shared filter compiler; src/filter-clauses.ts is the
// bridge to it.
-import { strip, toObject } from '@openpanel/shared';
+import { round, strip, toObject } from '@openpanel/shared';
import { assocPath, flatten, map, pathOr, pipe, prop, sort, uniq } from 'ramda';
import { cacheablePerDeps } from '../../cacheable-per-deps';
import { chQuery } from '../../ch-query';
@@ -10,7 +10,10 @@ import type { ServiceDeps, Services } from '../../services';
import { buildFilterWhere } from '../chart/src/table-filter-where';
import type { IClickhouseEvent } from '../event/event.service';
import type { IChartEventFilter } from '../report/report.constants';
-import type { IClickhouseSession } from '../session/session.service';
+import {
+ type IClickhouseSession,
+ withReadableCountry,
+} from '../session/session.service';
import {
convertClickhouseDateToJs,
formatClickhouseDate,
@@ -49,6 +52,7 @@ const RECENT_EVENTS_DEFAULT_LIMIT = 10;
const SESSIONS_DEFAULT_LIMIT = 20;
const FIND_PROFILES_DEFAULT_LIMIT = 20;
const FIND_PROFILES_MAX_LIMIT = 100;
+const SECONDS_PER_MINUTE = 60;
// clix always sent `session_timezone: 'UTC'`; the queries converted from clix
// keep sending it so their result sets stay identical.
@@ -68,13 +72,16 @@ export interface IProfileMetrics {
firstSeen: Date | null;
screenViews: number;
sessions: number;
+ /** Seconds. */
durationAvg: number;
+ /** Seconds. */
durationP90: number;
totalEvents: number;
uniqueDaysActive: number;
bounceRate: number;
avgEventsPerSession: number;
conversionEvents: number;
+ /** Seconds. */
avgTimeBetweenSessions: number;
revenue: number;
}
@@ -418,7 +425,10 @@ export async function getProfileWithEvents(
),
]);
- return { profile: profiles[0] ?? null, recent_events };
+ return {
+ profile: profiles[0] ?? null,
+ recent_events: recent_events.map(withReadableCountry),
+ };
}
export async function getProfileSessionsCore(
@@ -427,11 +437,12 @@ export async function getProfileSessionsCore(
profileId: string,
limit = SESSIONS_DEFAULT_LIMIT
): Promise<IClickhouseSession[]> {
- return chQuery<IClickhouseSession>(
+ const sessions = await chQuery<IClickhouseSession>(
deps,
profileSessionsQuery({ projectId, profileId, limit }),
CLIX_SESSION_TIMEZONE
);
+ return sessions.map(withReadableCountry);
}
export async function getProfileMetricsCore(
@@ -445,8 +456,16 @@ export async function getProfileMetricsCore(
if (!raw) {
throw new Error(`Profile not found or has no events: ${input.profileId}`);
}
+ return summarizeProfileMetrics(input.profileId, raw);
+}
+
+/** The profile metrics as the assistant and MCP tools report them. */
+export function summarizeProfileMetrics(
+ profileId: string,
+ raw: IProfileMetrics
+) {
return {
- profileId: input.profileId,
+ profileId,
firstSeen: raw.firstSeen,
lastSeen: raw.lastSeen,
sessions: raw.sessions,
@@ -454,8 +473,8 @@ export async function getProfileMetricsCore(
totalEvents: raw.totalEvents,
conversionEvents: raw.conversionEvents,
uniqueDaysActive: raw.uniqueDaysActive,
- avgSessionDurationMin: raw.durationAvg,
- p90SessionDurationMin: raw.durationP90,
+ avgSessionDurationMin: round(raw.durationAvg / SECONDS_PER_MINUTE),
+ p90SessionDurationMin: round(raw.durationP90 / SECONDS_PER_MINUTE),
avgEventsPerSession: raw.avgEventsPerSession,
avgTimeBetweenSessionsSec: raw.avgTimeBetweenSessions,
bounceRate: raw.bounceRate,
diff --git a/packages/core/src/modules/profile/src/profile-metrics-sql.test.ts b/packages/core/src/modules/profile/src/profile-metrics-sql.test.ts
index d0b19ebd5..8905f3e67 100644
--- a/packages/core/src/modules/profile/src/profile-metrics-sql.test.ts
+++ b/packages/core/src/modules/profile/src/profile-metrics-sql.test.ts
@@ -68,11 +68,25 @@ describe('profileMetricsQuery', () => {
expect(query).toContain(
'WHERE profile_id = {p3:String} AND project_id = {p4:String}'
);
+ expect(query).toContain(
+ 'PREWHERE project_id = {p5:String} AND profile_id = {p6:String}'
+ );
expect(query_params).toEqual({
p1: hostileProfile,
p2: hostileProject,
p3: hostileProfile,
p4: hostileProject,
+ p5: hostileProject,
+ p6: hostileProfile,
});
});
+
+ // Events sent before `identify()` carry the device id, so counting
+ // `session_start` events under the profile id missed the first session.
+ test('takes session figures from the collapsed sessions table', () => {
+ const { query } = render();
+ expect(query).toContain('FROM sessions FINAL');
+ expect(query).not.toContain("'session_start') as sessions");
+ expect(query).not.toContain('/ 60');
+ });
});
diff --git a/packages/core/src/modules/profile/src/sql.ts b/packages/core/src/modules/profile/src/sql.ts
index fadb92095..d189fa8a5 100644
--- a/packages/core/src/modules/profile/src/sql.ts
+++ b/packages/core/src/modules/profile/src/sql.ts
@@ -86,12 +86,20 @@ export function profileSearchCondition(
return sql`(${sql.join(perToken, ' AND ')})`;
}
+/**
+ * Session figures come from `sessions`, not from `session_start` events: the
+ * events sent before `identify()` carry the device id as `profile_id`, while
+ * the session row is rewritten to the final profile id. Durations are seconds.
+ */
export function profileMetricsQuery(query: {
profileId: string;
projectId: string;
}): SqlFragment {
const profileId = sql.string(query.profileId);
const projectId = sql.string(query.projectId);
+ // FINAL turns off automatic PREWHERE. Both PREWHERE columns are in the sort
+ // key, so a -1 and its +1 pass together; `sign` stays in WHERE so the
+ // collapse happens first.
return sql`
WITH profileSeen AS (
SELECT created_at as firstSeen, last_seen_at as lastSeen
@@ -102,16 +110,22 @@ export function profileMetricsQuery(query: {
eventStats AS (
SELECT
countIf(name = 'screen_view') as screenViews,
- countIf(name = 'session_start') as sessions,
- round(avgIf(duration, name = 'session_end' AND duration != 0) / 1000 / 60, 2) as durationAvg,
- round(quantilesExactInclusiveIf(0.9)(duration, name = 'session_end' AND duration != 0)[1] / 1000 / 60, 2) as durationP90,
count(*) as totalEvents,
count(DISTINCT toDate(created_at)) as uniqueDaysActive,
- round(avgIf(properties['__bounce'] = '1', name = 'session_end') * 100, 4) as bounceRate,
countIf(name NOT IN ('screen_view', 'session_start', 'session_end')) as conversionEvents,
sumIf(revenue, name = 'revenue') as revenue
FROM ${sql.id(TABLE.events)}
WHERE profile_id = ${profileId} AND project_id = ${projectId}
+ ),
+ sessionStats AS (
+ SELECT
+ count() as sessions,
+ round(ifNotFinite(avgIf(duration, duration != 0), 0) / 1000, 2) as durationAvg,
+ round(ifNotFinite(quantilesExactInclusiveIf(0.9)(duration, duration != 0)[1], 0) / 1000, 2) as durationP90,
+ round(ifNotFinite(avg(is_bounce), 0) * 100, 4) as bounceRate
+ FROM ${sql.id(TABLE.sessions)} FINAL
+ PREWHERE project_id = ${projectId} AND profile_id = ${profileId}
+ WHERE sign = 1
)
SELECT
(SELECT lastSeen FROM profileSeen) as lastSeen,
@@ -130,7 +144,7 @@ export function profileMetricsQuery(query: {
ELSE round(dateDiff('second', (SELECT firstSeen FROM profileSeen), (SELECT lastSeen FROM profileSeen)) / nullIf(sessions - 1, 0), 1)
END as avgTimeBetweenSessions,
revenue
- FROM eventStats
+ FROM eventStats CROSS JOIN sessionStats
`;
}