Metric Management Interface

**Referenced Files in This Document** - [[metric.proto]](file/bi-proto/metric/v1/metric.proto) - [[metric_http.pb.go]](file/bi-proto/metric/v1/metric-http.pb.go) - [[metric_grpc.pb.go]](file/bi-proto/metric/v1/metric-grpc.pb.go) - [[metric.proto]](file/bi-server/api/metric/v1/metric.proto) - [[metric_http.pb.go]](file/bi-server/api/metric/v1/metric-http.pb.go) - [[metric_grpc.pb.go]](file/bi-server/api/metric/v1/metric-grpc.pb.go) - [[page.tsx]](file/ui-web/src/app/metrics/page.tsx) - [[MetricTooltip.tsx]](file/ui-web/src/components/metrictooltip.tsx) - [[DerivedMetricModal.tsx]](file/ui-web/src/components/modals/derivedmetricmodal.tsx) - [[OrderMetricModal.tsx]](file/ui-web/src/components/modals/ordermetricmodal.tsx) - [[FormulaMetricModal.tsx]](file/ui-web/src/components/modals/formulametricmodal.tsx) - [[metrics.json]](file/ui-web/src/data/metrics.json) - [[field_visible_config.proto]](file/bi-proto/analysis/v1/field-visible-config.proto) - [[field_visible_config_http.pb.go]](file/bi-proto/analysis/v1/field-visible-config-http.pb.go) - [[field_visible_config_grpc.pb.go]](file/bi-proto/analysis/v1/field-visible-config-grpc.pb.go) - [[field_visible_config.proto]](file/bi-server/api/analysis/v1/field-visible-config.proto) - [[field_visible_config_http.pb.go]](file/bi-server/api/analysis/v1/field-visible-config-http.pb.go) - [[field_visible_config_grpc.pb.go]](file/bi-server/api/analysis/v1/field-visible-config-grpc.pb.go) - [[field_visible_config.go]](file/bi-analysis/internal/biz/field-visible-config.go) - [[field_visible_config.go]](file/bi-analysis/internal/data/field-visible-config.go) - [[field_visible_config.go]](file/bi-server/internal/service/field-visible-config.go) - [[field_visible_config.go]](file/bi-basic/internal/service/field-visible-config.go) - [[sql_builder.go]](file/bi-analysis/internal/biz/sql-builder.go) - [[sql_validator.go]](file/bi-analysis/internal/biz/sql-validator.go) - [[sql_formula.go]](file/bi-analysis/internal/biz/sql-formula.go) - [[field_meta.proto]](file/bi-proto/analysis/v1/field-meta.proto) - [[field_meta_http.pb.go]](file/bi-proto/analysis/v1/field-meta-http.pb.go) - [[field_meta_grpc.pb.go]](file/bi-proto/analysis/v1/field-meta-grpc.pb.go) - [[field_meta.proto]](file/bi-server/api/analysis/v1/field-meta.proto) - [[field_meta_http.pb.go]](file/bi-server/api/analysis/v1/field-meta-http.pb.go) - [[field_meta_grpc.pb.go]](file/bi-server/api/analysis/v1/field-meta-grpc.pb.go) - [[field_meta.go]](file/bi-analysis/internal/biz/field-meta.go) - [[field_meta.go]](file/bi-analysis/internal/data/field-meta.go) - [[field_meta.go]](file/bi-server/internal/service/field-meta.go) - [[field_meta.go]](file/bi-basic/internal/service/field-meta.go) - [[field.proto]](file/bi-proto/analysis/v1/field.proto) - [[field_http.pb.go]](file/bi-proto/analysis/v1/field-http.pb.go) - [[field_grpc.pb.go]](file/bi-proto/analysis/v1/field-grpc.pb.go) - [[field.proto]](file/bi-server/api/analysis/v1/field.proto) - [[field_http.pb.go]](file/bi-server/api/analysis/v1/field-http.pb.go) - [[field_grpc.pb.go]](file/bi-server/api/analysis/v1/field-grpc.pb.go) - [[field.go]](file/bi-analysis/internal/biz/field.go) - [[field.go]](file/bi-analysis/internal/data/field.go) - [[field.go]](file/bi-server/internal/service/field.go) - [[field.go]](file/bi-basic/internal/service/field.go) - [[table.proto]](file/bi-proto/analysis/v1/table.proto) - [[table_http.pb.go]](file/bi-proto/analysis/v1/table-http.pb.go) - [[table_grpc.pb.go]](file/bi-proto/analysis/v1/table-grpc.pb.go) - [[table.proto]](file/bi-server/api/analysis/v1/table.proto) - [[table_http.pb.go]](file/bi-server/api/analysis/v1/table-http.pb.go) - [[table_grpc.pb.go]](file/bi-server/api/analysis/v1/table-grpc.pb.go) - [[table.go]](file/bi-analysis/internal/biz/table.go) - [[table.go]](file/bi-analysis/internal/data/table.go) - [[table.go]](file/bi-server/internal/service/table.go) - [[table.go]](file/bi-basic/internal/service/table.go) - [[dimension.proto]](file/bi-proto/analysis/v1/dimension.proto) - [[dimension_http.pb.go]](file/bi-proto/analysis/v1/dimension-http.pb.go) - [[dimension_grpc.pb.go]](file/bi-proto/analysis/v1/dimension-grpc.pb.go) - [[dimension.proto]](file/bi-server/api/analysis/v1/dimension.proto) - [[dimension_http.pb.go]](file/bi-server/api/analysis/v1/dimension-http.pb.go) - [[dimension_grpc.pb.go]](file/bi-server/api/analysis/v1/dimension-grpc.pb.go) - [[dimension.go]](file/bi-analysis/internal/biz/dimension.go) - [[dimension.go]](file/bi-analysis/internal/data/dimension.go) - [[dimension.go]](file/bi-server/internal/service/dimension.go) - [[dimension.go]](file/bi-basic/internal/service/dimension.go) - [[field_group.proto]](file/bi-proto/analysis/v1/field-group.proto) - [[field_group_http.pb.go]](file/bi-proto/analysis/v1/field-group-http.pb.go) - [[field_group_grpc.pb.go]](file/bi-proto/analysis/v1/field-group-grpc.pb.go) - [[field_group.proto]](file/bi-server/api/analysis/v1/field-group.proto) - [[field_group_http.pb.go]](file/bi-server/api/analysis/v1/field-group-http.pb.go) - [[field_group_grpc.pb.go]](file/bi-server/api/analysis/v1/field-group-grpc.pb.go) - [[field_group.go]](file/bi-analysis/internal/biz/field-group.go) - [[field_group.go]](file/bi-analysis/internal/data/field-group.go) - [[field_group.go]](file/bi-server/internal/service/field-group.go) - [[field_group.go]](file/bi-basic/internal/service/field-group.go) - [[template.proto]](file/bi-proto/analysis/v1/template.proto) - [[template_http.pb.go]](file/bi-proto/analysis/v1/template-http.pb.go) - [[template_grpc.pb.go]](file/bi-proto/analysis/v1/template-grpc.pb.go) - [[template.proto]](file/bi-server/api/analysis/v1/template.proto) - [[template_http.pb.go]](file/bi-server/api/analysis/v1/template-http.pb.go) - [[template_grpc.pb.go]](file/bi-server/api/analysis/v1/template-grpc.pb.go) - [[template.go]](file/bi-analysis/internal/biz/template.go) - [[template.go]](file/bi-analysis/internal/data/template.go) - [[template.go]](file/bi-server/internal/service/template.go) - [[template.go]](file/bi-basic/internal/service/template.go) - [[query.proto]](file/bi-proto/analysis/v1/query.proto) - [[query_http.pb.go]](file/bi-proto/analysis/v1/query-http.pb.go) - [[query_grpc.pb.go]](file/bi-proto/analysis/v1/query-grpc.pb.go) - [[query.proto]](file/bi-server/api/analysis/v1/query.proto) - [[query_http.pb.go]](file/bi-server/api/analysis/v1/query-http.pb.go) - [[query_grpc.pb.go]](file/bi-server/api/analysis/v1/query-grpc.pb.go) - [[query.go]](file/bi-analysis/internal/biz/query.go) - [[query.go]](file/bi-analysis/internal/data/query.go) - [[query.go]](file/bi-server/internal/service/query.go) - [[query.go]](file/bi-basic/internal/service/query.go) - [[home.proto]](file/bi-proto/analysis/v1/home.proto) - [[home_http.pb.go]](file/bi-proto/analysis/v1/home-http.pb.go) - [[home_grpc.pb.go]](file/bi-proto/analysis/v1/home-grpc.pb.go) - [[home.proto]](file/bi-server/api/analysis/v1/home.proto) - [[home_http.pb.go]](file/bi-server/api/analysis/v1/home-http.pb.go) - [[home_grpc.pb.go]](file/bi-server/api/analysis/v1/home-grpc.pb.go) - [[home.go]](file/bi-analysis/internal/biz/home.go) - [[home.go]](file/bi-analysis/internal/data/home.go) - [[home.go]](file/bi-server/internal/service/home.go) - [[home.go]](file/bi-basic/internal/service/home.go) - [[common.proto]](file/bi-proto/analysis/v1/common.proto) - [[common_http.pb.go]](file/bi-proto/analysis/v1/common-http.pb.go) - [[common_grpc.pb.go]](file/bi-proto/analysis/v1/common-grpc.pb.go) - [[common.proto]](file/bi-server/api/analysis/v1/common.proto) - [[common_http.pb.go]](file/bi-server/api/analysis/v1/common-http.pb.go) - [[common_grpc.pb.go]](file/bi-server/api/analysis/v1/common-grpc.pb.go) - [[config.proto]](file/bi-proto/analysis/v1/config.proto) - [[config_http.pb.go]](file/bi-proto/analysis/v1/config-http.pb.go) - [[config_grpc.pb.go]](file/bi-proto/analysis/v1/config-grpc.pb.go) - [[config.proto]](file/bi-server/api/analysis/v1/config.proto) - [[config_http.pb.go]](file/bi-server/api/analysis/v1/config-http.pb.go) - [[config_grpc.pb.go]](file/bi-server/api/analysis/v1/config-grpc.pb.go) - [[config.go]](file/bi-analysis/internal/biz/config.go) - [[config.go]](file/bi-analysis/internal/data/config.go) - [[config.go]](file/bi-server/internal/service/config.go) - [[config.go]](file/bi-basic/internal/service/config.go) - [[field_group.go]](file/bi-basic/internal/service/field-group.go) - [[field_meta.go]](file/bi-basic/internal/service/field-meta.go) - [[field.go]](file/bi-basic/internal/service/field.go) - [[field_visible_config.go]](file/bi-basic/internal/service/field-visible-config.go) - [[table.go]](file/bi-basic/internal/service/table.go) - [[dimension.go]](file/bi-basic/internal/service/dimension.go) - [[template.go]](file/bi-basic/internal/service/template.go) - [[query.go]](file/bi-basic/internal/service/query.go) - [[home.go]](file/bi-basic/internal/service/home.go) - [[config.go]](file/bi-basic/internal/service/config.go)

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendices

Introduction

This document describes the Metric Management Interface, focusing on the hierarchical metric classification system, filtering mechanisms, and visualization controls. It explains the metric explorer component, category-based navigation, and search functionality. It also documents the metric configuration interface, including visibility settings, calculation formulas, and data source mappings, and details the integration with the bi-analysis service for metric definitions, the field visibility configuration system, and real-time metric updates. Examples are included for creating custom metrics, configuring metric hierarchies, and implementing advanced filtering with date ranges and segmentation. Performance considerations and caching strategies are addressed for large metric catalogs.

Project Structure

The Metric Management Interface spans frontend and backend components:

• Frontend (Next.js app): Provides the metric explorer UI, modal-based configuration forms, and tooltip-driven help.
• Backend (gRPC/HTTP services): Defines metric types and configurations, exposes CRUD APIs, and integrates with analysis services for field metadata, visibility, and query building.

Diagram sources

• [page.tsx]
• [metric.proto]
• [field_meta.proto]
• [field_visible_config.proto]
• [sql_builder.go]

Section sources

• [page.tsx]
• [metric.proto]

Core Components

• Metric Explorer UI: Renders metric groups, supports search, and previews help images.
• Metric Configuration Modals: Allow creation of derived, order, and formula metrics via the MetricService API.
• Metric Tooltip: Displays help content and images for each metric.
• Field Visibility Config: Controls whether fields appear in dashboards and reports.
• Field Metadata: Describes available fields, tables, and dimensions for metric construction.
• SQL Builder and Validation: Ensures safe and correct metric expressions and filters.

Section sources

• [page.tsx]
• [MetricTooltip.tsx]
• [DerivedMetricModal.tsx]
• [OrderMetricModal.tsx]
• [FormulaMetricModal.tsx]
• [metrics.json]
• [metric.proto]
• [field_visible_config.proto]
• [field_meta.proto]
• [sql_builder.go]

Architecture Overview

The Metric Management Interface follows a layered architecture:

• Presentation Layer: Next.js components render the metric explorer and configuration modals.
• API Layer: gRPC/HTTP endpoints expose MetricService and related analysis services.
• Business Logic Layer: SQL builder, validator, and formula engine enforce correctness and safety.
• Data Layer: Field metadata, visibility, tables, and dimensions define the metric catalog.

Diagram sources

• [metric_http.pb.go]
• [metric_grpc.pb.go]
• [page.tsx]

Detailed Component Analysis

Metric Explorer Component

• Category-based navigation: Groups metrics by domain (e.g., Traffic, Financial, Regional).
• Search functionality: Filters metrics by name; highlights popular metrics when no query is present.
• Help preview: Clicking an image opens a modal preview.

Diagram sources

• [page.tsx]
• [page.tsx]
• [page.tsx]

Section sources

• [page.tsx]
• [page.tsx]
• [page.tsx]

Metric Configuration Interface

• Types: Basic, Derived, Order, Formula.
• Derived metrics: Aggregate a source field over time range.
• Order metrics: Apply time basis and query conditions.
• Formula metrics: Define expressions with dependencies on other metrics.

Diagram sources

• [metric.proto]

Section sources

• [metric.proto]

Field Visibility Configuration System

• Purpose: Control which fields are visible in dashboards and reports.
• Integration: Exposed via HTTP/GRPC endpoints and consumed by the UI and analysis services.
• Data model: Defines visibility rules per field and context.

Diagram sources

• [field_visible_config_http.pb.go]
• [field_visible_config_grpc.pb.go]

Section sources

• [field_visible_config.proto]
• [field_visible_config_http.pb.go]
• [field_visible_config_grpc.pb.go]

Field Metadata and Data Source Mappings

• Field metadata: Describes available fields, their types, and relationships.
• Tables and Dimensions: Define the logical schema underlying metrics.
• Field Groups: Logical collections of fields for navigation and filtering.

Diagram sources

• [field_meta.proto]
• [table.proto]
• [dimension.proto]

Section sources

• [field_meta.proto]
• [table.proto]
• [dimension.proto]

Metric Definition Lifecycle

• Create: POST /v1/metrics with Metric payload.
• Update: PUT /v1/metrics/{metric.id} with FieldMask for partial updates.
• Delete: DELETE /v1/metrics/{id}.
• List: GET /v1/metrics returns grouped metrics.

Diagram sources

• [metric_http.pb.go]
• [metric_grpc.pb.go]

Section sources

• [metric_http.pb.go]
• [metric_grpc.pb.go]

Advanced Filtering and Date Range Segmentation

• Query conditions: Order metrics support structured query_condition for segmentation.
• SQL Builder: Translates metric definitions into executable SQL with validations.
• Template and Home services: Provide reusable templates and home layouts for metric consumption.

Diagram sources

• [metric.proto]
• [sql_builder.go]
• [sql_validator.go]
• [sql_formula.go]

Section sources

• [metric.proto]
• [sql_builder.go]
• [sql_validator.go]
• [sql_formula.go]

Real-time Metric Updates

• Real-time charting: The UI integrates real-time charts for live dashboards.
• Field visibility: Dynamic visibility rules can alter which metrics are rendered.
• Template and home services: Provide preconfigured layouts that reflect real-time updates.

Section sources

• [RealtimeChart.tsx]
• [field_visible_config.proto]
• [template.proto]
• [home.proto]

Dependency Analysis

The Metric Management Interface depends on:

• MetricService for CRUD operations on metrics.
• FieldMeta, FieldVisibleConfig, Table, Dimension for data source and visibility.
• SQL Builder/Validator/Formula for safe metric computation.
• Template/Home for layout and reuse.

Diagram sources

• [metric.proto]
• [field_meta.proto]
• [field_visible_config.proto]
• [sql_builder.go]

Section sources

• [metric.proto]
• [field_meta.proto]
• [field_visible_config.proto]
• [sql_builder.go]

Performance Considerations

• Large metric catalogs:
  • Paginate metric listings and lazy-load help images.
  • Cache metric groups and metadata in the browser.
• Caching strategies:
  • HTTP caching for ListMetrics responses.
  • Local storage for frequently accessed tooltips and images.
  • CDN for static images referenced by metrics.
• SQL computation:
  • Pre-validate formulas and conditions to avoid runtime errors.
  • Use indexed fields and time-range filters to reduce scan sizes.
• Real-time updates:
  • Debounce frequent UI updates.
  • Use incremental refresh for charts and tables.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

• Metric creation fails:
  • Verify FieldMask usage for partial updates.
  • Ensure formula dependencies are resolvable and expressions are valid.
• Visibility issues:
  • Confirm FieldVisibleConfig rules match the current context.
  • Rebuild templates if visibility does not apply.
• Search not working:
  • Check metrics.json entries and ensure keys match metric names.
  • Validate search query normalization.

Section sources

• [metric_grpc.pb.go]
• [field_visible_config_grpc.pb.go]
• [page.tsx]

Conclusion

The Metric Management Interface provides a robust, extensible system for discovering, configuring, and consuming metrics. Its hierarchical classification, powerful filtering, and integration with field metadata and visibility enable precise control over metric presentation and computation. By leveraging SQL validation, caching, and real-time charting, it scales effectively for large catalogs while maintaining a responsive user experience.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Example Workflows

• Creating a custom derived metric:

  • Select "Derived" in the metrics page.
  • Choose source field, aggregation type, and time range field.
  • Submit via POST /v1/metrics.

• Creating an order-specific metric:

  • Select "Order".
  • Set order field, time basis, and query condition.
  • Submit via POST /v1/metrics.

• Creating a formula metric:

  • Select "Formula".
  • Enter expression and specify dependency metric IDs.
  • Submit via POST /v1/metrics.

• Configuring metric hierarchies:

  • Group metrics by domain (e.g., Traffic, Financial).
  • Use templates to standardize layouts.

• Advanced filtering with date ranges and segmentation:

  • Use OrderConfig query_condition to segment by date/time and attributes.
  • Apply FieldVisibleConfig to restrict visible fields per context.

Section sources

• [page.tsx]
• [metric.proto]
• [field_visible_config.proto]
• [template.proto]