Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions packages/insomnia-data/src/models/project.ts
Original file line number Diff line number Diff line change
Expand Up @@ -114,12 +114,28 @@ export interface GitProject extends BaseModel, CommonProject {
remoteId: null;
}

export interface KonnectProject extends LocalProject {
konnectControlPlaneId: string | null;
Comment thread
ZxBing0066 marked this conversation as resolved.
Resolved
konnectClusterType: string | null;
konnectDeploymentType: KonnectDeploymentType | null;
konnectRegion: string | null;
// Latest Kong Debugger session id for this project (control plane)
konnectDebugSessionId?: string | null;
}

export type Project = LocalProject | RemoteProject | GitProject;

export const isProject = (model: Pick<BaseModel, 'type'>): model is Project => model.type === type;

export const isProjectId = (id: string | null) => id?.startsWith(`${prefix}_`);

export const isKonnectProject = (project: Project): project is KonnectProject =>
isProject(project) &&
'konnectControlPlaneId' in project &&
'konnectRegion' in project &&
'konnectClusterType' in project &&
'konnectDeploymentType' in project;

export const optionalKeys: (keyof CommonProject)[] = [
'konnectControlPlaneId',
'konnectClusterType',
Expand Down
9 changes: 8 additions & 1 deletion packages/insomnia-data/src/models/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,14 @@ export type {
ResponseInfo,
RunnerResultPerRequestPerIteration,
} from './runner-test-result';
export type { Project, LocalProject, RemoteProject, GitProject, KonnectDeploymentType } from './project';
export type {
Project,
LocalProject,
RemoteProject,
GitProject,
KonnectProject,
KonnectDeploymentType,
} from './project';
export type { ProjectLintRuleset } from './project-lint-ruleset';
export type { Settings, ThemeSettings } from './settings';
export type { Stats } from './stats';
Expand Down
40 changes: 29 additions & 11 deletions packages/insomnia/src/konnect/__tests__/debug-trace-helper.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { describe, expect, it } from 'vitest';

import type { DebugTraceDetail } from '../debug-session-api';
import { findTraceIdsByRouteId, getRouteIdFromKonnectRouteKey } from '../debug-trace-helper';
import { getRouteIdFromKonnectRouteKey, type SpanTree, summarizeTrace } from '../debug-trace-helper';

const detail = (traceId: string, attributes: Record<string, any>[]): DebugTraceDetail => ({
traceId,
Expand Down Expand Up @@ -30,18 +30,36 @@ describe('getRouteIdFromKonnectRouteKey', () => {
});
});

describe('findTraceIdsByRouteId', () => {
const details = new Map([
['t1', detail('t1', [{ 'http.route': '/a' }, { 'proxy.kong.route.id': 'route-1' }])],
['t2', detail('t2', [{ 'proxy.kong.route.id': 'route-2' }])],
['t3', detail('t3', [{}])],
]);
describe('summarizeTrace', () => {
const treeWith = (attributes: Record<string, any>): SpanTree => ({
roots: [
{
span: { ...detail('t1', [attributes]).spans[0] },
name: 'span',
depth: 0,
startOffsetMs: 0,
durationMs: 1,
children: [],
},
],
totalMs: 1,
});

it('matches traces having a span with the same proxy.kong.route.id', () => {
expect([...findTraceIdsByRouteId(details, 'route-1')]).toEqual(['t1']);
it('reads the route id, method, protocol and url scheme from the latency span', () => {
const summary = summarizeTrace(
treeWith({
'proxy.kong.latency.total': 10,
'proxy.kong.route.id': 'route-1',
'http.request.method': 'GET',
'network.protocol.name': 'http',
'url.scheme': 'https',
}),
);
expect(summary).toMatchObject({ routeId: 'route-1', method: 'GET', protocol: 'http', urlScheme: 'https' });
});

it('matches nothing without a route id', () => {
expect(findTraceIdsByRouteId(details, null).size).toBe(0);
it('defaults the route fields to empty strings when absent', () => {
const summary = summarizeTrace(treeWith({ 'proxy.kong.latency.total': 10 }));
expect(summary).toMatchObject({ routeId: '', method: '', protocol: '', urlScheme: '' });
});
});
17 changes: 10 additions & 7 deletions packages/insomnia/src/konnect/debug-session-api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,13 @@ export type DebugErrorKind = 'unauthorized' | 'forbidden' | 'not_found' | 'rate_
export class DebugApiError extends Error {
kind: DebugErrorKind;
retryAfterMs?: number;
constructor(kind: DebugErrorKind, message: string, retryAfterMs?: number) {
responseText: string;
constructor(kind: DebugErrorKind, message: string, responseText: string, retryAfterMs?: number) {
super(message);
this.name = 'DebugApiError';
this.kind = kind;
this.retryAfterMs = retryAfterMs;
this.responseText = responseText;
}
}

Expand All @@ -67,28 +69,29 @@ export async function toDebugApiError(err: unknown): Promise<DebugApiError> {
if (isApiError(err)) {
const status = err.response.status;
const response = err.response;
const responseText = response.bodyUsed ? err.message || `HTTP ${status}` : await response.text();
if (status === 401) {
return new DebugApiError('unauthorized', 'Personal access token is invalid or expired.');
return new DebugApiError('unauthorized', 'Personal access token is invalid or expired.', responseText);
}
if (status === 403) {
return new DebugApiError('forbidden', 'Personal access token lacks permission for the debugger.');
return new DebugApiError('forbidden', 'Personal access token lacks permission for the debugger.', responseText);
}
if (status === 404) {
return new DebugApiError('not_found', 'Not found.');
return new DebugApiError('not_found', 'Not found.', responseText);
}
if (status === 429) {
const retryAfter = Number.parseInt(err.response.headers.get('Retry-After') ?? '', 10);
return new DebugApiError(
'rate_limited',
'Konnect rate limit reached.',
responseText,
Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : undefined,
);
}
const responseText = response.bodyUsed ? err.message || `HTTP ${status}` : await response.text();
throw new DebugApiError('unknown', `Konnect error: ${responseText}`);
throw new DebugApiError('unknown', `${responseText}`, responseText);
}
const message = err instanceof Error ? err.message : 'Could not reach Konnect.';
return new DebugApiError('network', message);
return new DebugApiError('network', message, '');
}

async function request<T>(
Expand Down
2 changes: 1 addition & 1 deletion packages/insomnia/src/konnect/debug-session-query.ts
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ export async function startOrAdoptDebugSession(
): Promise<DebugSession> {
const nodeIds = await listNodeIds(ctx);
if (nodeIds.length === 0) {
throw new DebugApiError('unknown', 'No data plane nodes are connected to this control plane.');
throw new DebugApiError('unknown', 'No data plane nodes are connected to this control plane.', '');
}
return createDebugSession(ctx, durationSecs, nodeIds);
}
Expand Down
73 changes: 57 additions & 16 deletions packages/insomnia/src/konnect/debug-trace-helper.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,19 @@
import type { DebugSession, DebugSpan, DebugTraceDetail, DebugTraceSummary } from './debug-session-api';
export type DebugSessionState = 'active' | 'cancelled' | 'completed' | 'completing' | 'timed_out';

// Attribute names used in debug traces
export const TRACE_ATTRIBUTE_NAMES = {
Comment thread
ZxBing0066 marked this conversation as resolved.
Resolved
HTTP_REQUEST_METHOD: 'http.request.method',
URL_FULL: 'url.full',
HTTP_ROUTE: 'http.route',
HTTP_RESPONSE_STATUS_CODE: 'http.response.status_code',
HTTP_REQUEST_SIZE: 'http.request.size',
HTTP_RESPONSE_SIZE: 'http.response.size',
PROTOCOL: 'network.protocol.name',
ROUTE_ID: 'proxy.kong.route.id',
URL_SCHEME: 'url.scheme',
};

// Derive the state of a debug session from its response
export function deriveSessionState(session: DebugSession): DebugSessionState {
if (session.stoppedAt) {
Expand Down Expand Up @@ -59,7 +72,7 @@ export interface SpanTree {
const NANOS_PER_MS = 1_000_000n;

// Span timestamps are unix nanoseconds as strings: too large for a JS number to hold exactly.
function toBigInt(value: string): bigint {
export function toBigInt(value: string): bigint {
try {
return BigInt(value);
} catch {
Expand Down Expand Up @@ -110,7 +123,6 @@ export function buildSpanTree(detail: DebugTraceDetail): SpanTree {
}
}

// Depth, owner and self time depend on the parent, so fill them in top-down once the tree is linked.
const finalize = (node: SpanNode, depth: number) => {
node.depth = depth;
node.children.sort((a, b) => a.startOffsetMs - b.startOffsetMs);
Expand All @@ -123,7 +135,7 @@ export function buildSpanTree(detail: DebugTraceDetail): SpanTree {
return { roots, totalMs };
}

/** Depth-first rows for the waterfall, skipping the children of collapsed spans. */
// Depth-first rows for the waterfall, skipping the children of collapsed spans.
export function flattenVisible(roots: SpanNode[], collapsed: ReadonlySet<string>): SpanNode[] {
const result: SpanNode[] = [];
const visit = (node: SpanNode) => {
Expand All @@ -137,6 +149,10 @@ export function flattenVisible(roots: SpanNode[], collapsed: ReadonlySet<string>
}

export interface TraceSummaryBreakdown {
routeId: string;
protocol: string;
method: string;
urlScheme: string;
totalMs: number;
kongMs: number;
upstreamMs: number;
Expand All @@ -145,6 +161,8 @@ export interface TraceSummaryBreakdown {
kongPct: number;
upstreamPct: number;
clientPct: number;
requestSize: number;
responseSize: number;
thirdPartyPct: number;
}

Expand All @@ -155,6 +173,7 @@ const LATENCY_ATTRIBUTES = {
upstream: 'proxy.kong.latency.upstream',
client: 'proxy.kong.latency.client',
thirdParty: 'proxy.kong.latency.3p.total_io',
protocol: 'network.protocol.name',
};

// Some numeric attributes come back as strings (e.g. `proxy.kong.http.response.body.size`).
Expand Down Expand Up @@ -189,6 +208,12 @@ export function summarizeTrace(tree: SpanTree): TraceSummaryBreakdown | null {
const thirdPartyMs = readMs(span.attributes, LATENCY_ATTRIBUTES.thirdParty) ?? 0;
const sum = kongMs + upstreamMs + clientMs + thirdPartyMs;
const pct = (value: number) => (sum > 0 ? (value / sum) * 100 : 0);
const requestSize = span.attributes[TRACE_ATTRIBUTE_NAMES.HTTP_REQUEST_SIZE] || 0;
const responseSize = span.attributes[TRACE_ATTRIBUTE_NAMES.HTTP_RESPONSE_SIZE] || 0;
const protocol = span.attributes[TRACE_ATTRIBUTE_NAMES.PROTOCOL] || '';
const method = span.attributes[TRACE_ATTRIBUTE_NAMES.HTTP_REQUEST_METHOD] || '';
const routeId = span.attributes[TRACE_ATTRIBUTE_NAMES.ROUTE_ID] || '';
const urlScheme = span.attributes[TRACE_ATTRIBUTE_NAMES.URL_SCHEME] || '';
return {
totalMs: readMs(span.attributes, LATENCY_ATTRIBUTES.total) ?? tree.totalMs,
kongMs,
Expand All @@ -199,6 +224,12 @@ export function summarizeTrace(tree: SpanTree): TraceSummaryBreakdown | null {
upstreamPct: pct(upstreamMs),
clientPct: pct(clientMs),
thirdPartyPct: pct(thirdPartyMs),
requestSize,
responseSize,
protocol,
method,
routeId,
urlScheme,
};
}

Expand All @@ -219,8 +250,6 @@ export function getTracePath(trace: Pick<DebugTraceSummary, 'url' | 'route'>): s
return trace.route ? normalizePath(trace.route) : null;
}

const ROUTE_ID_ATTRIBUTE = 'proxy.kong.route.id';

// konnectRouteKey is `${route.id}:${method}:${pathSegment}:${protocol}`
export function getRouteIdFromKonnectRouteKey(konnectRouteKey: string | null | undefined): string | null {
if (!konnectRouteKey) {
Expand All @@ -230,16 +259,28 @@ export function getRouteIdFromKonnectRouteKey(konnectRouteKey: string | null | u
return routeId;
}

/** Ids of the traces having a span served by the Kong route `routeId`. */
export function findTraceIdsByRouteId(details: Map<string, DebugTraceDetail>, routeId: string | null): Set<string> {
const matching = new Set<string>();
if (!routeId) {
return matching;
}
for (const [traceId, detail] of details) {
if (detail.spans.some(span => span.attributes[ROUTE_ID_ATTRIBUTE] === routeId)) {
matching.add(traceId);
interface ParsedKonnectError {
title?: string;
detail?: string;
traceId?: string;
raw: string;
}

// Parse Konnect JSON error message
export const parseKonnectError = (message: string): ParsedKonnectError | null => {
try {
const json = JSON.parse(message);
if (!json || typeof json !== 'object' || Array.isArray(json)) {
return null;
}
const title = typeof json.title === 'string' ? json.title : '';
const detail = typeof json.detail === 'string' ? json.detail : '';
if (!title && !detail) {
return null;
}
const instance = typeof json.instance === 'string' ? json.instance : undefined;
return { title, detail, traceId: instance, raw: JSON.stringify(json, null, 2) };
} catch {
return null;
}
return matching;
}
};
1 change: 1 addition & 0 deletions packages/insomnia/src/konnect/links.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { getKongDocsOrigin, getKonnectCloudOrigin } from '../common/constants';
export const getPluginHubUrl = () => `${getKongDocsOrigin()}/plugins/`;
export const getPluginPriorityDocsUrl = () => `${getKongDocsOrigin()}/gateway/entities/plugin/#plugin-priority`;
export const getDeckApplyDocsUrl = () => `${getKongDocsOrigin()}/deck/gateway/apply/`;
export const getDebugSessionsUrl = () => `${getKongDocsOrigin()}/observability/debugger/`;

const encodePathSegment = (value: string) => encodeURIComponent(value);

Expand Down
57 changes: 57 additions & 0 deletions packages/insomnia/src/konnect/route-request-lookup.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import type { GrpcRequest, Request, WebSocketRequest, Workspace, WorkspaceChildrenForScope } from 'insomnia-data';
import { models } from 'insomnia-data';

import { getRouteIdFromKonnectRouteKey, type TraceSummaryBreakdown } from './debug-trace-helper';

export interface KonnectRouteRequest {
request: Request | WebSocketRequest | GrpcRequest;
workspaceId: string;
workspaceName: string;
routeId: string;
/** Method and protocol segments of the konnectRouteKey. */
method: string;
protocol: string;
}

// Local requests of the given workspaces that were synced from a Konnect route.
export function listKonnectRouteRequests(
workspaces: Pick<Workspace, '_id' | 'name'>[],
childrenByWorkspaceId: ReadonlyMap<string, WorkspaceChildrenForScope<'collection' | 'design'>>,
): KonnectRouteRequest[] {
return workspaces.flatMap(workspace =>
(childrenByWorkspaceId.get(workspace._id)?.data.requestsAndGroups ?? []).flatMap(doc => {
if (
!models.request.isRequest(doc) &&
!models.webSocketRequest.isWebSocketRequest(doc) &&
!models.grpcRequest.isGrpcRequest(doc)
) {
return [];
}
const routeId = getRouteIdFromKonnectRouteKey(doc.konnectRouteKey);
if (!routeId) {
return [];
}
// konnectRouteKey is `${route.id}:${method}:${pathSegment}:${protocol}`; the path may contain ':'.
const segments = doc.konnectRouteKey!.split(':');
const method = (segments[1] ?? '').toUpperCase();
const protocol = (segments.at(-1) ?? '').toUpperCase();
return [{ request: doc, workspaceId: workspace._id, workspaceName: workspace.name, routeId, method, protocol }];
}),
);
}

// Picks the local request for a trace: same Kong route, and the same HTTP method and protocol as the trace.
export function findRouteRequestForTrace(
routeRequests: KonnectRouteRequest[],
trace: Pick<TraceSummaryBreakdown, 'method' | 'urlScheme' | 'routeId'>,
): KonnectRouteRequest | null {
const method = trace.method?.toUpperCase();
return (
routeRequests.find(
candidate =>
trace.routeId === candidate.routeId &&
candidate.method.toUpperCase() === method &&
candidate.protocol.toUpperCase() === trace.urlScheme?.toUpperCase(),
) ?? null
);
}
Loading
Loading