Query Services

public class MetricsQueryService implements Service {
    
    /**
     * Reads single metric value for given conditions
     * @param condition Metrics query conditions including name and entity
     * @param duration Time range for the query
     * @return Nullable value result with debugging info
     * @throws IOException If query execution fails
     */
    public NullableValue readMetricsValue(MetricsCondition condition, Duration duration) 
        throws IOException;
    
    /**
     * Reads time-series metrics values over duration
     * @param condition Metrics query conditions
     * @param duration Time range with step configuration
     * @return Time-series values with timestamps
     * @throws IOException If query execution fails
     */
    public MetricsValues readMetricsValues(MetricsCondition condition, Duration duration) 
        throws IOException;
    
    /**
     * Reads labeled metrics values for multi-dimensional data
     * @param condition Base metrics query conditions
     * @param labels List of label key-value pairs for filtering
     * @param duration Time range for the query
     * @return List of labeled time-series values
     * @throws IOException If query execution fails
     */
    public List<MetricsValues> readLabeledMetricsValues(MetricsCondition condition, 
        List<KeyValue> labels, Duration duration) throws IOException;
    
    /**
     * Reads heat map metrics data for percentile analysis
     * @param condition Metrics query conditions for heat map data
     * @param duration Time range for aggregation
     * @return Heat map data structure with value distributions
     * @throws IOException If query execution fails
     */
    public HeatMap readHeatMap(MetricsCondition condition, Duration duration) 
        throws IOException;
    
    /**
     * Reads sampled records for detailed analysis
     * @param condition Query conditions for sample selection
     * @param duration Time range for sampling
     * @return List of sampled records
     * @throws IOException If query execution fails
     */
    public List<SelectedRecord> readSampledRecords(MetricsCondition condition, Duration duration) 
        throws IOException;
    
    /**
     * Executes expression-based queries for complex metrics calculations
     * @param expression Metrics query expression (MQE format)
     * @param duration Time range for evaluation
     * @return Expression evaluation results
     * @throws IOException If expression execution fails
     */
    public ExpressionResult queryExpressionSeries(String expression, Duration duration) 
        throws IOException;
}

public class TraceQueryService implements Service {
    
    /**
     * Queries trace list with pagination and filtering
     * @param condition Trace query conditions
     * @return Paginated trace list
     * @throws IOException If query fails
     */
    public TraceBrief queryBasicTraces(TraceQueryCondition condition) throws IOException;
    
    /**
     * Queries detailed trace by trace ID
     * @param traceId Unique trace identifier
     * @return Complete trace with all spans
     * @throws IOException If query fails
     */
    public Trace queryTrace(String traceId) throws IOException;
    
    /**
     * Queries trace segments by segment ID
     * @param segmentId Segment identifier
     * @return Trace segment with span details
     * @throws IOException If query fails
     */
    public List<Segment> queryTraceSegments(String segmentId) throws IOException;
    
    /**
     * Queries span details by span ID
     * @param spanId Span identifier within trace
     * @return Detailed span information
     * @throws IOException If query fails
     */
    public Span querySpan(String spanId) throws IOException;
}

public class TopologyQueryService implements Service {
    
    /**
     * Queries global service topology
     * @param duration Time range for topology data
     * @return Service topology with nodes and edges
     * @throws IOException If query fails
     */
    public Topology getGlobalTopology(Duration duration) throws IOException;
    
    /**
     * Queries service topology around specific service
     * @param serviceId Central service identifier
     * @param duration Time range for analysis
     * @return Service-centric topology
     * @throws IOException If query fails
     */
    public Topology getServiceTopology(String serviceId, Duration duration) throws IOException;
    
    /**
     * Queries instance topology for service
     * @param serviceId Parent service identifier
     * @param duration Time range for instance data
     * @return Instance topology within service
     * @throws IOException If query fails
     */
    public ServiceInstanceTopology getServiceInstanceTopology(String serviceId, Duration duration) 
        throws IOException;
    
    /**
     * Queries endpoint topology for service
     * @param serviceId Parent service identifier
     * @param duration Time range for endpoint data
     * @return Endpoint relationships within service
     * @throws IOException If query fails
     */
    public Topology getEndpointTopology(String serviceId, Duration duration) throws IOException;
}

public class MetadataQueryService implements Service {
    
    /**
     * Lists all services with optional keyword filtering
     * @param keyword Optional service name filter
     * @return List of services
     * @throws IOException If query fails
     */
    public List<Service> getAllServices(String keyword) throws IOException;
    
    /**
     * Lists services within time duration
     * @param duration Time range for service activity
     * @return List of active services
     * @throws IOException If query fails
     */
    public List<Service> listServices(Duration duration) throws IOException;
    
    /**
     * Gets service instances for specific service
     * @param serviceId Parent service identifier
     * @param duration Time range for instance activity
     * @return List of service instances
     * @throws IOException If query fails
     */
    public List<ServiceInstance> getServiceInstances(String serviceId, Duration duration) 
        throws IOException;
    
    /**
     * Gets endpoints for specific service
     * @param serviceId Parent service identifier
     * @param keyword Optional endpoint name filter
     * @param limit Maximum number of results
     * @return List of service endpoints
     * @throws IOException If query fails
     */
    public List<Endpoint> getEndpoints(String serviceId, String keyword, int limit) 
        throws IOException;
    
    /**
     * Finds service by exact name match
     * @param serviceName Service name to search
     * @return Service entity or null if not found
     * @throws IOException If query fails
     */
    public Service findService(String serviceName) throws IOException;
    
    /**
     * Finds service instance by name
     * @param serviceId Parent service identifier
     * @param instanceName Instance name to search
     * @return Service instance or null if not found
     * @throws IOException If query fails
     */
    public ServiceInstance findServiceInstance(String serviceId, String instanceName) 
        throws IOException;
    
    /**
     * Finds endpoint by name within service
     * @param serviceId Parent service identifier
     * @param endpointName Endpoint name to search
     * @return Endpoint entity or null if not found
     * @throws IOException If query fails
     */
    public Endpoint findEndpoint(String serviceId, String endpointName) throws IOException;
}

public class LogQueryService implements Service {
    
    /**
     * Queries logs with filtering conditions and pagination
     * @param condition Log query conditions including service, instance, keywords
     * @return Paginated log results
     * @throws IOException If query fails
     */
    public Logs queryLogs(LogQueryCondition condition) throws IOException;
    
    /**
     * Tests log query conditions for validation
     * @param condition Log query conditions to test
     * @return Test result with validation status
     * @throws IOException If test fails
     */
    public LogTestResponse test(LogQueryCondition condition) throws IOException;
}

public class AlarmQueryService implements Service {
    
    /**
     * Queries alarms with pagination and filtering
     * @param duration Time range for alarm search
     * @param scope Alarm scope (service, instance, endpoint, etc.)
     * @param keyword Optional keyword filter
     * @param paging Pagination configuration
     * @param tags Optional tag filters
     * @return Paginated alarm results
     * @throws IOException If query fails
     */
    public Alarms getAlarm(Duration duration, Scope scope, String keyword, 
                         Pagination paging, List<Tag> tags) throws IOException;
}

public class MetricsMetadataQueryService implements Service {
    
    /**
     * Lists all available metrics
     * @param regex Optional regex pattern for metric name filtering
     * @return List of metric metadata
     * @throws IOException If query fails
     */
    public List<MetricDefinition> listMetrics(String regex) throws IOException;
    
    /**
     * Gets definition for specific metric
     * @param metricName Metric name to describe
     * @return Detailed metric definition with type and scope
     * @throws IOException If query fails
     */
    public MetricDefinition getMetricDefinition(String metricName) throws IOException;
    
    /**
     * Lists metric types (gauge, counter, histogram, etc.)
     * @return List of available metric types
     * @throws IOException If query fails
     */
    public List<String> listMetricTypes() throws IOException;
}

public class AggregationQueryService implements Service {
    
    /**
     * Performs aggregation over metrics data
     * @param aggregation Aggregation configuration (sum, avg, max, min, etc.)
     * @param condition Query conditions
     * @param duration Time range
     * @return Aggregated result
     * @throws IOException If aggregation fails
     */
    public AggregationResult aggregate(Aggregation aggregation, MetricsCondition condition, 
                                     Duration duration) throws IOException;
    
    /**
     * Performs top-N aggregation
     * @param condition Query conditions
     * @param duration Time range
     * @param topN Number of top results
     * @param order Sort order (ASC/DESC)
     * @return Top-N results
     * @throws IOException If query fails
     */
    public List<TopNEntity> getTopN(MetricsCondition condition, Duration duration, 
                                  int topN, Order order) throws IOException;
}

public class HierarchyQueryService implements Service {
    
    /**
     * Gets service hierarchy structure
     * @param serviceId Root service identifier
     * @param layer Hierarchy layer (auto, k8s, mesh, etc.)
     * @return Service hierarchy tree
     * @throws IOException If query fails
     */
    public ServiceHierarchy getServiceHierarchy(String serviceId, String layer) 
        throws IOException;
    
    /**
     * Gets instance hierarchy for service
     * @param serviceId Parent service identifier
     * @param instanceId Instance identifier
     * @return Instance hierarchy information
     * @throws IOException If query fails
     */
    public InstanceHierarchy getInstanceHierarchy(String serviceId, String instanceId) 
        throws IOException;
    
    /**
     * Lists available hierarchy layers
     * @return List of supported hierarchy layers
     * @throws IOException If query fails
     */
    public List<String> listLayers() throws IOException;
}

public class DurationUtils {
    
    /**
     * Converts duration to time range in milliseconds
     * @param duration Duration configuration
     * @return Start and end timestamps
     */
    public static TimeRange durationToTimeRange(Duration duration);
    
    /**
     * Calculates step interval based on duration
     * @param duration Duration configuration
     * @return Step interval in milliseconds
     */
    public static long calculateStep(Duration duration);
    
    /**
     * Validates duration configuration
     * @param duration Duration to validate
     * @return True if duration is valid
     */
    public static boolean isValidDuration(Duration duration);
}

public class PaginationUtils {
    
    /**
     * Calculates offset from page number and size
     * @param pageNum Page number (1-based)
     * @param pageSize Number of items per page
     * @return Offset for database query
     */
    public static int calculateOffset(int pageNum, int pageSize);
    
    /**
     * Creates pagination from offset and limit
     * @param offset Starting offset
     * @param limit Maximum items to return
     * @return Pagination configuration
     */
    public static Pagination createPagination(int offset, int limit);
}

public class PointOfTime {
    
    private long timestamp;
    
    /**
     * Creates point of time from timestamp
     * @param timestamp Unix timestamp in milliseconds
     */
    public PointOfTime(long timestamp);
    
    /**
     * Gets timestamp
     * @return Unix timestamp in milliseconds
     */
    public long getTimestamp();
    
    /**
     * Converts to time bucket with downsampling
     * @param downSampling Downsampling level
     * @return Time bucket value
     */
    public long toTimeBucket(DownSampling downSampling);
}

/**
 * Metrics query conditions
 */
public class MetricsCondition {
    private String name;
    private String entity;
    private Map<String, String> labels;
    
    public String getName();
    public String getEntity();
    public Map<String, String> getLabels();
}

/**
 * Trace query conditions
 */
public class TraceQueryCondition {
    private String serviceId;
    private String serviceInstanceId;
    private String endpointId;
    private String traceId;
    private int minDuration;
    private int maxDuration;
    private TraceState traceState;
    private QueryOrder queryOrder;
    private Pagination paging;
    
    public String getServiceId();
    public int getMinDuration();
    public int getMaxDuration();
    public TraceState getTraceState();
    public Pagination getPaging();
}

/**
 * Log query conditions
 */
public class LogQueryCondition {
    private String serviceId;
    private String serviceInstanceId;
    private String endpointId;
    private String relatedTraceId;
    private ContentType contentType;
    private List<String> keywords;
    private List<String> excludingKeywords;
    private Pagination paging;
    
    public String getServiceId();
    public List<String> getKeywords();
    public Pagination getPaging();
}

/**
 * Nullable value result with debugging info
 */
public class NullableValue {
    private Long value;
    private boolean isEmptyValue;
    private String debuggingMessage;
    
    public Long getValue();
    public boolean isEmptyValue();
    public String getDebuggingMessage();
}

/**
 * Time-series metrics values
 */
public class MetricsValues {
    private String label;
    private List<KVInt> values;
    
    public String getLabel();
    public List<KVInt> getValues();
}

/**
 * Key-value integer pair with timestamp
 */
public class KVInt {
    private long id;      // timestamp
    private long value;
    
    public long getId();
    public long getValue();
}

/**
 * Heat map data structure
 */
public class HeatMap {
    private List<HeatMapColumn> values;
    
    public List<HeatMapColumn> getValues();
}

/**
 * Heat map column with bucket data
 */
public class HeatMapColumn {
    private long id;      // timestamp
    private List<Long> values;  // bucket values
    
    public long getId();
    public List<Long> getValues();
}

/**
 * Complete trace information
 */
public class Trace {
    private List<Span> spans;
    
    public List<Span> getSpans();
}

/**
 * Trace span details
 */
public class Span {
    private String traceId;
    private String segmentId;
    private int spanId;
    private int parentSpanId;
    private List<Ref> refs;
    private String serviceCode;
    private String serviceInstanceName;
    private String startTime;
    private String endTime;
    private String endpointName;
    private String type;
    private String peer;
    private String component;
    private boolean isError;
    private String layer;
    private List<KeyValue> tags;
    private List<LogEntity> logs;
    
    public String getTraceId();
    public String getEndpointName();
    public boolean isError();
    public List<KeyValue> getTags();
}

/**
 * Service topology structure
 */
public class Topology {
    private List<Node> nodes;
    private List<Call> calls;
    
    public List<Node> getNodes();
    public List<Call> getCalls();
}

/**
 * Topology node (service, instance, endpoint)
 */
public class Node {
    private String id;
    private String name;
    private String type;
    private boolean isReal;
    
    public String getId();
    public String getName();
    public boolean isReal();
}

/**
 * Service call relationship
 */
public class Call {
    private String source;
    private String target;
    private List<String> detectPoints;
    
    public String getSource();
    public String getTarget();
    public List<String> getDetectPoints();
}

// Query single metric value
MetricsCondition condition = new MetricsCondition();
condition.setName("service_cpm");
condition.setEntity("dGVzdC1zZXJ2aWNl.1");  // encoded service ID

Duration duration = new Duration();
duration.setStart("2023-01-01 00:00:00");
duration.setEnd("2023-01-01 01:00:00");
duration.setStep(Step.MINUTE);

NullableValue result = metricsQueryService.readMetricsValue(condition, duration);
if (!result.isEmptyValue()) {
    System.out.println("Service CPM: " + result.getValue());
}

// Query time-series metrics
MetricsValues timeSeries = metricsQueryService.readMetricsValues(condition, duration);
for (KVInt point : timeSeries.getValues()) {
    System.out.println("Time: " + point.getId() + ", Value: " + point.getValue());
}

// Query labeled metrics (multi-dimensional)
List<KeyValue> labels = Arrays.asList(
    new KeyValue("status_code", "200"),
    new KeyValue("method", "GET")
);

List<MetricsValues> labeledResults = metricsQueryService.readLabeledMetricsValues(
    condition, labels, duration
);

for (MetricsValues labeledSeries : labeledResults) {
    System.out.println("Label: " + labeledSeries.getLabel());
    // Process time series for this label
}

// Query trace list with filtering
TraceQueryCondition traceCondition = new TraceQueryCondition();
traceCondition.setServiceId("service-123");
traceCondition.setMinDuration(1000);  // minimum 1 second
traceCondition.setMaxDuration(10000); // maximum 10 seconds
traceCondition.setTraceState(TraceState.ERROR);

Pagination paging = new Pagination();
paging.setPageNum(1);
paging.setPageSize(20);
traceCondition.setPaging(paging);

TraceBrief traceBrief = traceQueryService.queryBasicTraces(traceCondition);
for (BasicTrace trace : traceBrief.getTraces()) {
    System.out.println("Trace ID: " + trace.getTraceId());
    System.out.println("Duration: " + trace.getDuration() + "ms");
}

// Query detailed trace
String traceId = "trace-456";
Trace detailedTrace = traceQueryService.queryTrace(traceId);
for (Span span : detailedTrace.getSpans()) {
    System.out.println("Span: " + span.getEndpointName());
    System.out.println("Duration: " + (span.getEndTime() - span.getStartTime()));
    if (span.isError()) {
        System.out.println("Error span found!");
    }
}

// Query global service topology
Duration duration = createDuration("2023-01-01 00:00:00", "2023-01-01 01:00:00");
Topology globalTopology = topologyQueryService.getGlobalTopology(duration);

System.out.println("Services: " + globalTopology.getNodes().size());
System.out.println("Calls: " + globalTopology.getCalls().size());

for (Node node : globalTopology.getNodes()) {
    System.out.println("Service: " + node.getName() + " (ID: " + node.getId() + ")");
}

for (Call call : globalTopology.getCalls()) {
    System.out.println("Call: " + call.getSource() + " -> " + call.getTarget());
}

// Query service-specific topology
String serviceId = "service-123";
Topology serviceTopology = topologyQueryService.getServiceTopology(serviceId, duration);

// List all services
List<Service> allServices = metadataQueryService.getAllServices(null);
for (Service service : allServices) {
    System.out.println("Service: " + service.getName());
    
    // Get instances for this service
    List<ServiceInstance> instances = metadataQueryService.getServiceInstances(
        service.getId(), duration
    );
    
    for (ServiceInstance instance : instances) {
        System.out.println("  Instance: " + instance.getName());
    }
    
    // Get endpoints for this service
    List<Endpoint> endpoints = metadataQueryService.getEndpoints(
        service.getId(), null, 100
    );
    
    for (Endpoint endpoint : endpoints) {
        System.out.println("  Endpoint: " + endpoint.getName());
    }
}

// Find specific service
Service specificService = metadataQueryService.findService("my-service");
if (specificService != null) {
    System.out.println("Found service: " + specificService.getId());
}

// Query logs with filtering
LogQueryCondition logCondition = new LogQueryCondition();
logCondition.setServiceId("service-123");
logCondition.setKeywords(Arrays.asList("error", "exception"));
logCondition.setContentType(ContentType.TEXT);

Pagination logPaging = new Pagination();
logPaging.setPageNum(1);
logPaging.setPageSize(50);
logCondition.setPaging(logPaging);

Logs logs = logQueryService.queryLogs(logCondition);
for (Log log : logs.getLogs()) {
    System.out.println("Log: " + log.getContent());
    System.out.println("Timestamp: " + log.getTimestamp());
    if (log.getTraceId() != null) {
        System.out.println("Related trace: " + log.getTraceId());
    }
}

/**
 * Duration configuration for time-based queries
 */
public class Duration {
    private String start;
    private String end;
    private Step step;
    
    public String getStart();
    public String getEnd();
    public Step getStep();
}

/**
 * Time step for duration queries
 */
public enum Step {
    SECOND, MINUTE, HOUR, DAY
}

/**
 * Pagination configuration
 */
public class Pagination {
    private int pageNum;
    private int pageSize;
    private boolean needTotal;
    
    public int getPageNum();
    public int getPageSize();
    public boolean isNeedTotal();
}

/**
 * Key-value pair for labels and tags
 */
public class KeyValue {
    private String key;
    private String value;
    
    public KeyValue(String key, String value);
    public String getKey();
    public String getValue();
}

/**
 * Query module definition
 */
public class QueryModule extends ModuleDefine {
    public static final String NAME = "query";
    
    @Override
    public String name();
    
    @Override
    public Class[] services();
}