get_consumer_requests

Instructions

Implementation Reference

• src/operations/analytics.ts:196-317 (handler)

  The main handler function that queries API requests filtered by consumer ID, optionally success/failure status, computes aggregated statistics (average latency, success rate, status code and service distributions), and returns structured metadata, statistics, and detailed request list.

  export async function getConsumerRequests(
    api: KongApi,
    consumerId: string,
    timeRange: string,
    successOnly = false,
    failureOnly = false,
    maxResults = 100
  ) {
    try {
      // Build filters array
      const filters: ApiRequestFilter[] = [
        {
          field: "consumer",
          operator: "in",
          value: [consumerId]
        }
      ];
  
      // Add status code filter if needed
      if (successOnly) {
        filters.push({
          field: "status_code_grouped",
          operator: "in",
          value: ["2XX"]
        });
      } else if (failureOnly) {
        filters.push({
          field: "status_code_grouped",
          operator: "in",
          value: ["4XX", "5XX"]
        });
      }
  
      const result = await api.queryApiRequests(timeRange, filters, maxResults);
      
      // Calculate some statistics if we have results
      let avgLatency = 0;
      let successRate = 0;
      let statusCodeCounts: Record<string, number> = {};
      let serviceBreakdown: Record<string, { count: number, statusCodes: Record<string, number> }> = {};
      
      if (result.results.length > 0) {
        // Calculate average latency
        avgLatency = result.results.reduce((sum, req) => sum + (req.latencies_response_ms || 0), 0) / result.results.length;
        
        // Calculate success rate
        const successCount = result.results.filter(req => {
          const status = req.status_code ?? req.response_http_status ?? 0; // Default to 0 if both are undefined
          return status >= 200 && status < 300;
        }).length;
        successRate = (successCount / result.results.length) * 100;
        
        // Count status codes
        result.results.forEach(req => {
          const status = req.status_code ?? req.response_http_status ?? 0; // Default to 0 if both are undefined
          statusCodeCounts[status] = (statusCodeCounts[status] || 0) + 1;
        });
        
        // Service breakdown
        result.results.forEach(req => {
          const service = req.gateway_service ?? "unknown"; // Using ?? instead of || for null/undefined handling
          if (!serviceBreakdown[service]) {
            serviceBreakdown[service] = { count: 0, statusCodes: {} };
          }
          serviceBreakdown[service].count++;
          
          const status = req.status_code ?? req.response_http_status ?? 0; // Default to 0 if both are undefined
          serviceBreakdown[service].statusCodes[status] = (serviceBreakdown[service].statusCodes[status] || 0) + 1;
        });
      }
  
      // Format the response in a readable way
      return {
        metadata: {
          consumerId: consumerId,
          totalRequests: result.results.length,
          timeRange: {
            start: result.meta.time_range.start,
            end: result.meta.time_range.end,
          },
          filters: {
            successOnly,
            failureOnly
          }
        },
        statistics: {
          averageLatencyMs: parseFloat(avgLatency.toFixed(2)),
          successRate: parseFloat(successRate.toFixed(2)),
          statusCodeDistribution: Object.entries(statusCodeCounts).map(([code, count]) => ({
            statusCode: parseInt(code),
            count: count,
            percentage: parseFloat(((count / result.results.length) * 100).toFixed(2))
          })).sort((a, b) => b.count - a.count),
          serviceDistribution: Object.entries(serviceBreakdown).map(([service, data]) => ({
            serviceId: service,
            count: data.count,
            percentage: parseFloat(((data.count / result.results.length) * 100).toFixed(2)),
            statusCodeBreakdown: Object.entries(data.statusCodes).map(([code, count]) => ({
              statusCode: parseInt(code),
              count: count
            })).sort((a, b) => b.count - a.count)
          })).sort((a, b) => b.count - a.count)
        },
        requests: result.results.map(req => ({
          timestamp: req.request_start,
          httpMethod: req.http_method,
          uri: req.request_uri,
          statusCode: req.status_code || req.response_http_status,
          serviceId: req.gateway_service,
          routeId: req.route,
          latency: {
            totalMs: req.latencies_response_ms,
            gatewayMs: req.latencies_kong_gateway_ms,
            upstreamMs: req.latencies_upstream_ms
          },
          clientIp: req.client_ip,
          traceId: req.trace_id
        }))
      };
    } catch (error) {
      throw error;
    }

• src/parameters.ts:49-60 (schema)

  Zod input schema defining required consumerId, timeRange, optional successOnly/failureOnly flags, and maxResults for the get_consumer_requests tool.

  export const getConsumerRequestsParameters = () => z.object({
    consumerId: z.string()
      .describe("Consumer ID to filter by (obtainable from analyze-failed-requests or query-api-requests tools)"),
    timeRange: timeRangeSchema,
    successOnly: z.boolean()
      .default(false)
      .describe("Show only successful (2xx) requests"),
    failureOnly: z.boolean()
      .default(false)
      .describe("Show only failed (non-2xx) requests"),
    maxResults: pageSizeSchema,
  });

• src/tools.ts:24-30 (registration)

  Tool definition object exported from tools.ts listing, specifying method name, name, description prompt function, parameters schema function, and category; used for MCP tool registration.

  {
    method: "get_consumer_requests",
    name: "Get Consumer Requests",
    description: prompts.getConsumerRequestsPrompt(),
    parameters: parameters.getConsumerRequestsParameters(),
    category: "analytics"
  },

• src/index.ts:62-71 (registration)

  Switch case dispatcher in the main MCP server that maps the 'get_consumer_requests' method to the analytics handler function, passing API instance and validated args.

  case "get_consumer_requests":
    result = await analytics.getConsumerRequests(
      this.api,
      args.consumerId,
      args.timeRange,
      args.successOnly,
      args.failureOnly,
      args.maxResults
    );
    break;