Skip to main content
Preview
Preview Feature — This feature is currently in preview and under active development. APIs and functionality may change. We recommend testing thoroughly before using in production.

Logs

The Logs module provides comprehensive logging and analytics for your applications and products within the Ductape platform. Track API calls, monitor performance, and analyze usage patterns across all your services.

When to Use Logs​

Use Logs when you need:

  • Usage Analytics - Track how your APIs and features are being used
  • Error Monitoring - Identify and debug failures in your integrations
  • Performance Insights - Monitor response times and throughput
  • Audit Trails - Keep records of all actions for compliance
  • Trend Analysis - Understand usage patterns over time

Quick Example​

import Ductape from '@ductape/sdk';

const ductape = new Ductape({
  accessKey: 'your-access-key',
});

// Initialize with a product tag
await ductape.logs.init('my-product');

// Fetch recent logs
const logs = await ductape.logs.fetch({
  component: 'product',
  type: 'actions',
  groupBy: 'day',
  limit: 20,
});

console.log('Metrics:', logs.metrics);
console.log('Weekly Trends:', logs.weeklyMetrics);
console.log('Log Entries:', logs.logs.data);

Initialization​

Before fetching logs, initialize the Logs service with your product or app tag:

// Initialize with a product tag
await ductape.logs.init('my-product');

// Or initialize with an app tag
await ductape.logs.init('my-app');

Fetching Logs​

The fetch method retrieves logs based on query parameters. You can fetch logs for either apps or products.

Basic Usage​

// Fetch product logs
const productLogs = await ductape.logs.fetch({
  component: 'product',
  type: 'database',
  status: 'success',
  limit: 50,
});

// Fetch app logs
const appLogs = await ductape.logs.fetch({
  component: 'app',
  type: 'actions',
  groupBy: 'day',
  limit: 20,
});

Query Parameters​

Common Parameters​

ParameterTypeRequiredDescription
component'app' | 'product'YesLog source type
typestringNoAnalysis type (see below)
groupBy'day' | 'week' | 'month' | 'year'NoTime grouping for aggregations
searchstringNoSearch term for filtering
pagenumberNoPage number (starts at 1)
limitnumberNoResults per page
status'success' | 'processing' | 'fail'NoFilter by status

Log Types​

TypeDescription
actionsAPI action invocations
databaseDatabase operations
appsApp-level activities
processBackground processes
featureFeature usage
integrationsThird-party integrations

App-Specific Parameters​

ParameterTypeDescription
tagstringTag identifier (valid when type='actions')
envstringEnvironment filter
namestringName filter
actionstringSpecific action filter

Product-Specific Parameters​

ParameterTypeDescription
envstringEnvironment filter
namestringName filter
actionstringSpecific action filter

Response Structure​

App Logs Response​

interface AppLogsResponse {
  // Summary metrics
  metrics: {
    totalActions: number;
    totalEnvironments: number;
    totalAuthorizations: number;
  };

  // Week-over-week comparisons
  weeklyMetrics: {
    totalProductsConnected: TrendMetric;
    totalFeaturesUsingAction: TrendMetric;
    errors: TrendMetricWithPercentage;
  };

  // Time-series data for charts
  usageData: {
    requestsOverTime: TimeSeriesData[];
    successOverTime: TimeSeriesData[];
    failuresOverTime: TimeSeriesData[];
  };

  // Paginated log entries
  logs: {
    metadata: {
      total: number;
      page: number;
      limit: number;
      totalPages: number;
    };
    data: LogEntry[];
  };
}

interface TrendMetric {
  current: number;
  previous: number;
  difference: number;
  trend: '>' | '<' | '=';
}

interface TrendMetricWithPercentage extends TrendMetric {
  percentageChange: string;
}

Product Logs Response​

interface ProductLogsResponse {
  // Summary metrics
  metrics: {
    totalApps: number;
    totalDatabases: number;
    totalFeatures: number;
  };

  // Week-over-week comparisons
  weeklyMetrics: {
    totalActionsCalled: TrendMetric;
    totalActiveIssues: TrendMetric;
    errors: TrendMetricWithPercentage;
  };

  // Time-series data for charts
  usageData: {
    requestsOverTime: TimeSeriesData[];
    successOverTime: TimeSeriesData[];
    failuresOverTime: TimeSeriesData[];
  };

  // Paginated log entries
  logs: {
    metadata: {
      total: number;
      page: number;
      limit: number;
      totalPages: number;
    };
    data: LogEntry[];
  };
}

Examples​

Monitor Error Rates​

Track errors across your product:

const errorLogs = await ductape.logs.fetch({
  component: 'product',
  status: 'fail',
  groupBy: 'day',
  limit: 100,
});

// Check error trend
const { errors } = errorLogs.weeklyMetrics;
if (errors.trend === '>') {
  console.log(`Errors increased by ${errors.percentageChange}`);
}

// Get error details
errorLogs.logs.data.forEach(log => {
  console.log(`Error: ${log.message} at ${log.timestamp}`);
});

Search Logs​

Find specific log entries:

const searchResults = await ductape.logs.fetch({
  component: 'product',
  search: 'payment failed',
  type: 'integrations',
  limit: 50,
});

Paginated Results​

Fetch logs with pagination:

async function getAllLogs(component: 'app' | 'product') {
  const allLogs = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await ductape.logs.fetch({
      component,
      page,
      limit: 100,
    });

    allLogs.push(...result.logs.data);
    hasMore = page < result.logs.metadata.totalPages;
    page++;
  }

  return allLogs;
}

Filter by Environment​

Monitor specific environments:

const prodLogs = await ductape.logs.fetch({
  component: 'product',
  status: 'fail',
  groupBy: 'week',
});

console.log('Production errors this week:', prodLogs.weeklyMetrics.errors.current);

Dashboard Analytics​

Get data for a monitoring dashboard:

const analytics = await ductape.logs.fetch({
  component: 'product',
  groupBy: 'day',
});

// Display metrics
console.log('Connected Apps:', analytics.metrics.totalApps);
console.log('Active Databases:', analytics.metrics.totalDatabases);
console.log('Features in Use:', analytics.metrics.totalFeatures);

// Plot time-series
analytics.usageData.requestsOverTime.forEach(point => {
  console.log(`${point.date}: ${point.count} requests`);
});

Error Handling​

The fetch method throws errors in these cases:

try {
  const logs = await ductape.logs.fetch({
    component: 'product',
    type: 'actions',
  });
} catch (error) {
  if (error.message.includes('not initialized')) {
    // Call init() first
    await ductape.logs.init('my-product');
  } else if (error.message.includes('invalid parameter')) {
    // Check parameter values
  } else {
    // API or network error
    console.error('Failed to fetch logs:', error);
  }
}

See Also​