IGNIS Observability Package

A production-ready React analytics dashboard package for real-time data visualization, observability metrics, and comprehensive system monitoring. Built with TypeScript, Tailwind CSS, and React for seamless integration into modern applications.

Perfect for: Monitoring dashboards, analytics platforms, system observability, real-time metrics visualization.

� Table of Contents

• Key Features
• Installation
• Package Exports
• API Reference
• Configuration
• React Integration Guide
• Next.js Integration
• Styling & Customization
• Troubleshooting
• Additional Resources

�🚀 Key Features

• Production-Ready - Battle-tested components with comprehensive type safety
• Direct Configuration - Clean prop-based setup, no global variables or complex setup
• React Components - Use as a React component or standalone web component
• Flexible Authentication - Support for custom headers, JWT tokens, and API key authentication
• Responsive Design - Mobile-friendly, adaptive dashboard that works on all screen sizes
• TypeScript Support - Full type definitions for enhanced developer experience
• Real-time Updates - Stream live metrics and analytics data
• Event Callbacks - onError and onDataLoad callbacks for advanced integration
• Customizable Styling - Built with Tailwind CSS for easy customization

📦 Installation

Install the package from npm:

npm install @tenarai-ignis/observability

Peer Dependencies

This package requires React 16.8+ and React DOM 16.8+:

npm install react react-dom

Quick Start

import { ReactAnalyticsDashboard } from '@tenarai-ignis/observability';
import '@tenarai-ignis/observability/styles';

function App() {
  return (
    <ReactAnalyticsDashboard 
      config={{
        analyticsApiUrl: 'https://api.example.com/analytics',
        observabilityApiUrl: 'https://api.example.com/observability',
        accountsApiUrl: 'https://api.example.com/accounts',
        flowsApiUrl: 'https://api.example.com/flows',
        token: 'your-auth-token'
      }}
    />
  );
}

📤 Package Exports

The following are available as named imports from @tenarai-ignis/observability:

| Export | Type | Description | |--------|------|-------------| | ReactAnalyticsDashboard | React Component | Main dashboard component for React apps | | AnalyticsConfig | TypeScript Interface | Config type definition | | DashboardProps | TypeScript Interface | Props type for the dashboard component | | ChartData | TypeScript Interface | Chart data structure type | | FilterOptions | TypeScript Interface | Filter options type |

import {
  ReactAnalyticsDashboard,
  type AnalyticsConfig,
  type DashboardProps,
  type ChartData,
  type FilterOptions
} from '@tenarai-ignis/observability';

// Styles must be imported separately
import '@tenarai-ignis/observability/styles';

🌐 API Reference

Overview

The dashboard makes the following API calls. All endpoints receive the Authorization: Bearer {token} header plus any custom headers you provide.

1. Analytics API

Method: POST
URL: {analyticsApiUrl}

Request Body

{
  "start_time": "2026-07-01T00:00:00.000Z",
  "end_time": "2026-07-10T23:59:59.999Z",
  "stride": { "minutes": 720 },
  "flow_ids": ["flow-abc123", "flow-def456"],
  "account_ids": ["acc-001"],
  "domains": ["domain-001"]
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | start_time | ISO 8601 string | ✅ Yes | Start of reporting window | | end_time | ISO 8601 string | ✅ Yes | End of reporting window | | stride.minutes | number | ✅ Yes | Aggregation interval in minutes (e.g. 15, 60, 720) | | flow_ids | string[] | No | Filter by specific flow IDs | | account_ids | string[] | No | Filter by specific account IDs | | domains | string[] | No | Filter by specific domains |

Expected Response

{
  "charts": [
    {
      "title": "Trace Count",
      "data": [
        { "timestamp": "2026-07-01T00:00:00Z", "value": 142 },
        { "timestamp": "2026-07-01T12:00:00Z", "value": 198 },
        { "timestamp": "2026-07-02T00:00:00Z", "value": 165 }
      ]
    },
    {
      "title": "LLM Count",
      "data": [
        { "timestamp": "2026-07-01T00:00:00Z", "value": 320 },
        { "timestamp": "2026-07-01T12:00:00Z", "value": 415 }
      ]
    },
    {
      "title": "Trace Latency",
      "data": [
        { "timestamp": "2026-07-01T00:00:00Z", "value": 1240 },
        { "timestamp": "2026-07-01T12:00:00Z", "value": 980 }
      ]
    },
    {
      "title": "Trace Error Rate",
      "data": [
        { "timestamp": "2026-07-01T00:00:00Z", "value": 0.03 },
        { "timestamp": "2026-07-01T12:00:00Z", "value": 0.01 }
      ]
    }
  ],
  "top_flows": [
    {
      "name": "Customer Support Flow",
      "executions": 1452,
      "success_rate": 0.97,
      "avg_response_time": 1340,
      "cost": 12.45
    },
    {
      "name": "Data Enrichment Pipeline",
      "executions": 876,
      "success_rate": 0.91,
      "avg_response_time": 2100,
      "cost": 8.20
    }
  ],
  "sub_sections": [
    {
      "title": "LLM Calls",
      "charts": [
        {
          "title": "LLM Count",
          "data": [
            { "timestamp": "2026-07-01T00:00:00Z", "value": 320 }
          ]
        }
      ]
    }
  ]
}

| Field | Type | Description | |-------|------|-------------| | charts | array | Time-series charts for each metric tab | | charts[].title | string | Chart title (e.g. "Trace Count", "LLM Count", "Trace Latency") | | charts[].data | array | Array of { timestamp, value } data points | | top_flows | array | Top performing flows with execution stats | | top_flows[].name | string | Flow name | | top_flows[].executions | number | Total execution count | | top_flows[].success_rate | number | Success rate (0–1 decimal, e.g. 0.97 = 97%) | | top_flows[].avg_response_time | number | Average response time in milliseconds | | top_flows[].cost | number | Total cost in USD | | sub_sections | array | Additional grouped chart sections |

2. Observability API

Method: POST
URL: {observabilityApiUrl}

Request Body

{
  "start_date": "2026-07-01",
  "end_date": "2026-07-10",
  "flow_ids": ["flow-abc123"],
  "account_ids": ["acc-001"],
  "domains": ["domain-001"]
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | start_date | YYYY-MM-DD string | ✅ Yes | Start date | | end_date | YYYY-MM-DD string | ✅ Yes | End date | | flow_ids | string[] | No | Filter by flow IDs (empty array = all flows) | | account_ids | string[] | No | Filter by account IDs | | domains | string[] | No | Filter by domains |

Expected Response

{
  "observability_summary": {
    "total_traces": 4821,
    "total_llm_calls": 12340,
    "total_tokens": 5420000,
    "avg_latency_ms": 1350,
    "error_rate": 0.024,
    "total_cost_usd": 48.75,
    "success_rate": 0.976,
    "active_flows": 12,
    "p95_latency_ms": 3200,
    "p99_latency_ms": 5800
  }
}

| Field | Type | Description | |-------|------|-------------| | observability_summary.total_traces | number | Total number of traces in period | | observability_summary.total_llm_calls | number | Total LLM API calls made | | observability_summary.total_tokens | number | Total tokens consumed | | observability_summary.avg_latency_ms | number | Average end-to-end latency in ms | | observability_summary.error_rate | number | Error rate (0–1 decimal) | | observability_summary.total_cost_usd | number | Total cost in USD | | observability_summary.success_rate | number | Overall success rate (0–1 decimal) | | observability_summary.active_flows | number | Number of active flows in period | | observability_summary.p95_latency_ms | number | P95 latency in milliseconds | | observability_summary.p99_latency_ms | number | P99 latency in milliseconds |

3. Accounts API

Method: GET
URL: {accountsApiUrl}

Expected Response

The dashboard supports multiple response shapes:

{
  "data": {
    "items": [
      {
        "id": "acc-001",
        "name": "Acme Corp",
        "domain": "acme.com",
        "status": "active",
        "created_at": "2025-01-15T10:00:00Z"
      },
      {
        "id": "acc-002",
        "name": "Globex Inc",
        "domain": "globex.com",
        "status": "active",
        "created_at": "2025-03-20T08:30:00Z"
      }
    ],
    "meta": {
      "total": 2,
      "page": 1,
      "per_page": 50
    }
  }
}

Note: The component also handles flat array responses [{...}] or { accounts: [{...}] } shapes automatically.

| Field | Type | Description | |-------|------|-------------| | id | string | Unique account identifier (used for filtering) | | name | string | Display name shown in the filter dropdown | | domain | string | Account domain | | status | string | Account status (active, inactive) |

4. Flows API

Method: GET
URL: {flowsApiUrl}

Expected Response

{
  "data": {
    "items": [
      {
        "id": "flow-abc123",
        "name": "Customer Support Flow",
        "description": "Handles customer support queries using LLM",
        "status": "active",
        "created_at": "2025-06-01T09:00:00Z",
        "updated_at": "2026-07-01T14:00:00Z"
      },
      {
        "id": "flow-def456",
        "name": "Data Enrichment Pipeline",
        "description": "Enriches CRM data using AI workflows",
        "status": "active",
        "created_at": "2025-07-10T11:00:00Z",
        "updated_at": "2026-06-28T10:00:00Z"
      }
    ],
    "meta": {
      "total": 2,
      "page": 1,
      "per_page": 50
    }
  }
}

Note: The component also handles flat array responses [{...}] or { flows: [{...}] } shapes automatically.

| Field | Type | Description | |-------|------|-------------| | id | string | Unique flow identifier (used in filter flow_ids arrays) | | name | string | Display name shown in the filter dropdown | | description | string | Optional flow description | | status | string | Flow status (active, inactive) |

⚙️ Configuration

AnalyticsConfig Reference

The AnalyticsConfig object configures the dashboard component with all required and optional properties:

interface AnalyticsConfig {
  // Required: API Endpoints (full URLs)
  analyticsApiUrl: string;        // Analytics POST endpoint
  observabilityApiUrl: string;    // Observability POST endpoint
  accountsApiUrl: string;         // Accounts GET endpoint
  flowsApiUrl: string;            // Flows GET endpoint

  // Required: Authentication
  token: string;                  // JWT or Bearer token

  // Optional: Features
  enableAccountFlowsFilter?: boolean;  // Show account/flow/domain dropdowns (default: true)
  maxDays?: number;                    // Max selectable date range in days
  showFilters?: boolean;               // Show/hide filter bar (default: true)
  theme?: 'light' | 'dark';           // Dashboard theme

  // Optional: Extra request headers
  headers?: Record<string, string>;

  // Optional: Callbacks
  onError?: (error: Error) => void;
  onDataLoad?: (data: any) => void;
}

Configuration Examples

Basic Configuration:

const config: AnalyticsConfig = {
  analyticsApiUrl: 'https://api.example.com/api/v1/observability/dashboard',
  observabilityApiUrl: 'https://api.example.com/api/v1/observability/summary',
  accountsApiUrl: 'https://api.example.com/api/v1/accounts',
  flowsApiUrl: 'https://api.example.com/api/v1/flows/all',
  token: sessionStorage.getItem('auth_token')
};

Advanced Configuration with Headers & Callbacks:

const config: AnalyticsConfig = {
  analyticsApiUrl: process.env.VITE_ANALYTICS_API,
  observabilityApiUrl: process.env.VITE_OBSERVABILITY_API,
  accountsApiUrl: process.env.VITE_ACCOUNTS_API,
  flowsApiUrl: process.env.VITE_FLOWS_API,
  token: getAuthToken(),
  enableAccountFlowsFilter: true,
  headers: {
    'x-api-key': process.env.VITE_API_KEY,
    'x-tenant-id': getCurrentTenantId(),
    'x-request-id': generateRequestId()
  },
  onError: (error) => {
    console.error('Dashboard error:', error);
    notifyUser('Failed to load metrics');
  },
  onDataLoad: (data) => {
    console.log('Dashboard data loaded:', data);
    updateLastRefreshTime();
  }
};

✅ React Integration Guide

Basic Usage

import React from 'react';
import { ReactAnalyticsDashboard, type AnalyticsConfig } from '@tenarai-ignis/observability';
import '@tenarai-ignis/observability/styles';

const Observability: React.FC = () => {
  const analyticsConfig: AnalyticsConfig = {
    analyticsApiUrl: 'https://api.example.com/api/v1/observability/dashboard',
    observabilityApiUrl: 'https://api.example.com/api/v1/observability/summary',
    accountsApiUrl: 'https://api.example.com/api/v1/accounts',
    flowsApiUrl: 'https://api.example.com/api/v1/flows/all',
    token: sessionStorage.getItem('auth_token'),
  };

  return (
    <div className="min-h-screen bg-gray-50">
      <ReactAnalyticsDashboard config={analyticsConfig} />
    </div>
  );
};

export default Observability;

Advanced Usage with Error Handling

const Observability: React.FC = () => {
  const [loading, setLoading] = React.useState(true);
  const [error, setError] = React.useState<string | null>(null);

  const analyticsConfig: AnalyticsConfig = {
    analyticsApiUrl: process.env.REACT_APP_ANALYTICS_API!,
    observabilityApiUrl: process.env.REACT_APP_OBSERVABILITY_API!,
    accountsApiUrl: process.env.REACT_APP_ACCOUNTS_API!,
    flowsApiUrl: process.env.REACT_APP_FLOWS_API!,
    token: getAuthToken(),
    enableAccountFlowsFilter: true,
    headers: {
      'x-api-key': process.env.REACT_APP_API_KEY,
    },
    onError: (err) => {
      console.error('Dashboard error:', err);
      setError(err.message || 'Failed to load dashboard');
    },
    onDataLoad: (data) => {
      console.log('Dashboard data loaded successfully');
      setLoading(false);
    }
  };

  if (error) {
    return <ErrorBoundary message={error} />;
  }

  return (
    <div className="min-h-screen bg-gray-50">
      {loading && <LoadingSpinner />}
      <ReactAnalyticsDashboard config={analyticsConfig} />
    </div>
  );
};

⚡ Next.js Integration

App Router (Next.js 13+)

The dashboard is a client-side component. Add 'use client' at the top:

// app/observability/page.tsx
'use client';

import { ReactAnalyticsDashboard, type AnalyticsConfig } from '@tenarai-ignis/observability';
import '@tenarai-ignis/observability/styles';

export default function ObservabilityPage() {
  const config: AnalyticsConfig = {
    analyticsApiUrl: process.env.NEXT_PUBLIC_ANALYTICS_API!,
    observabilityApiUrl: process.env.NEXT_PUBLIC_OBSERVABILITY_API!,
    accountsApiUrl: process.env.NEXT_PUBLIC_ACCOUNTS_API!,
    flowsApiUrl: process.env.NEXT_PUBLIC_FLOWS_API!,
    token: process.env.NEXT_PUBLIC_AUTH_TOKEN!,
  };

  return (
    <div className="container mx-auto">
      <ReactAnalyticsDashboard config={config} />
    </div>
  );
}

Pages Router (Next.js 12 and below)

Use dynamic import with ssr: false to prevent server-side rendering issues:

// pages/observability.tsx
import dynamic from 'next/dynamic';
import type { AnalyticsConfig } from '@tenarai-ignis/observability';

const ReactAnalyticsDashboard = dynamic(
  () => import('@tenarai-ignis/observability').then(mod => mod.ReactAnalyticsDashboard),
  { ssr: false }
);

export default function ObservabilityPage() {
  const config: AnalyticsConfig = {
    analyticsApiUrl: process.env.NEXT_PUBLIC_ANALYTICS_API!,
    observabilityApiUrl: process.env.NEXT_PUBLIC_OBSERVABILITY_API!,
    accountsApiUrl: process.env.NEXT_PUBLIC_ACCOUNTS_API!,
    flowsApiUrl: process.env.NEXT_PUBLIC_FLOWS_API!,
    token: process.env.NEXT_PUBLIC_AUTH_TOKEN!,
  };

  return <ReactAnalyticsDashboard config={config} />;
}

Environment Variables (.env.local)

NEXT_PUBLIC_ANALYTICS_API=https://api.example.com/api/v1/observability/dashboard
NEXT_PUBLIC_OBSERVABILITY_API=https://api.example.com/api/v1/observability/summary
NEXT_PUBLIC_ACCOUNTS_API=https://api.example.com/api/v1/accounts
NEXT_PUBLIC_FLOWS_API=https://api.example.com/api/v1/flows/all
NEXT_PUBLIC_AUTH_TOKEN=your-jwt-token

🎨 Styling & Customization

Import Styles

Always import the styles in your application:

import '@tenarai-ignis/observability/styles';

Tailwind CSS Customization

The dashboard is built with Tailwind CSS. You can customize colors and appearance by modifying your tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3B82F6',
        secondary: '#10B981',
      },
    },
  },
};

Custom Container Styling

<div className="custom-dashboard-container">
  <ReactAnalyticsDashboard 
    config={config}
  />
</div>

<style>{`
  .custom-dashboard-container {
    background-color: #f9fafb;
    border-radius: 12px;
    box-shadow: 0 1px 3px rgba(0,0,0,0.1);
  }
`}</style>

🔍 Troubleshooting

Common Issues

Dashboard Not Loading Data:

• Verify API endpoints are accessible and respond with correct data format
• Check authentication token is valid and not expired
• Ensure CORS is properly configured on your API server
• Check browser console for error messages

401 Unauthorized Errors:

• Verify the token is valid
• Check if token has expired (typically after 1 hour)
• Ensure token is passed in the correct format (JWT or Bearer)

Styling Issues:

• Ensure @tenarai-ignis/observability/styles is imported
• Verify Tailwind CSS is properly configured in your project
• Check for CSS conflicts with other libraries

Performance Issues:

• Consider implementing data pagination or filtering
• Use enableAccountFlowsFilter to reduce data volume
• Implement proper caching strategies on your API

Getting Help

If you encounter issues:

1. Check the browser console for error messages
2. Review API response format against documentation
3. Verify all required environment variables are set
4. Visit tenarai.com for support

📄 License

MIT License - Use freely in commercial and personal projects.

See LICENSE file for details.

Package Version: 0.0.2
Last Updated: July 2026
Published: @tenarai-ignis/observability on npm
Website: https://tenarai.com
Maintained by: Tenarai Ignis Team

Get Started Today: npm install @tenarai-ignis/observability