The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
package client
import (
"context"
"encoding/json"
"net/http"
"net/url"
"time"
"github.com/google/uuid"
)
// ExceptionGroup matches Traceway's models.ExceptionGroup. Hourly trends are
// only present on list responses; on the detail endpoint they're absent.
type ExceptionGroup struct {
ExceptionHash string `json:"exceptionHash"`
StackTrace string `json:"stackTrace"`
FirstSeen time.Time `json:"firstSeen"`
LastSeen time.Time `json:"lastSeen"`
Count uint64 `json:"count"`
HourlyTrend []ExceptionTrendPoint `json:"hourlyTrend,omitempty"`
}
// ExceptionTrendPoint is one entry in an exception's hourly trend.
type ExceptionTrendPoint struct {
Timestamp time.Time `json:"timestamp"`
Count uint64 `json:"count"`
}
// ListExceptionsRequest is the body for POST /api/exception-stack-traces.
// projectId travels as a URL query param (handled by ListExceptions), not in
// the body — the upstream RequireProjectAccess middleware reads it via
// c.Query("projectId").
type ListExceptionsRequest struct {
TimeRange TimeRange `json:"-"` // serialized as fromDate/toDate via MarshalJSON
Pagination PaginationParams `json:"pagination"`
OrderBy string `json:"orderBy,omitempty"`
Search string `json:"search,omitempty"`
SearchType string `json:"searchType,omitempty"`
IncludeArchived bool `json:"includeArchived,omitempty"`
}
// MarshalJSON expands TimeRange.From / TimeRange.To into top-level fromDate /
// toDate so the wire shape matches Traceway's ExceptionSearchRequest, and
// sends OrderBy as the column name the backend sorts on.
func (r ListExceptionsRequest) MarshalJSON() ([]byte, error) {
type alias ListExceptionsRequest
wire := struct {
FromDate time.Time `json:"fromDate"`
ToDate time.Time `json:"toDate"`
alias
}{
FromDate: r.TimeRange.From,
ToDate: r.TimeRange.To,
alias: alias(r),
}
wire.OrderBy = orderByColumn(r.OrderBy)
return jsonMarshalNoHTMLEscape(wire)
}
// ListExceptionsResponse mirrors the upstream PaginatedResponse[ExceptionGroup].
type ListExceptionsResponse struct {
Data []ExceptionGroup `json:"data"`
Pagination Pagination `json:"pagination"`
}
// ListExceptions returns one page of grouped exceptions for the given project.
func (c *Client) ListExceptions(ctx context.Context, projectID string, req ListExceptionsRequest) (*ListExceptionsResponse, error) {
path := "/api/exception-stack-traces?projectId=" + url.QueryEscape(projectID)
var resp ListExceptionsResponse
if err := c.do(ctx, http.MethodPost, path, req, &resp); err != nil {
return nil, err
}
return &resp, nil
}
// ExceptionStackTrace is one occurrence of a grouped exception. TraceId and
// SpanId name the span it was recorded on (empty when it arrived outside any
// trace), and TraceType is set only when that span is itself an endpoint, a
// task or an AI trace. RelatedEntity on the responses names the owner.
type ExceptionStackTrace struct {
Id uuid.UUID `json:"id"`
ExceptionHash string `json:"exceptionHash"`
StackTrace string `json:"stackTrace"`
RecordedAt time.Time `json:"recordedAt"`
TraceId string `json:"traceId,omitempty"`
SpanId string `json:"spanId,omitempty"`
TraceType string `json:"traceType,omitempty"`
ServerName string `json:"serverName,omitempty"`
AppVersion string `json:"appVersion,omitempty"`
IsMessage bool `json:"isMessage,omitempty"`
Attributes map[string]string `json:"attributes,omitempty"`
SessionId *uuid.UUID `json:"sessionId,omitempty"`
}
// RelatedEntity is the endpoint, task or AI trace an exception happened in:
// the one whose span it was recorded on, or the nearest one above that span.
// Id and RecordedAt feed straight into endpoints/tasks/ai-traces show, and
// TraceId into traces show.
type RelatedEntity struct {
TraceType string `json:"traceType"`
Id uuid.UUID `json:"id"`
Name string `json:"name"`
StatusCode int16 `json:"statusCode"`
Duration time.Duration `json:"duration"`
RecordedAt time.Time `json:"recordedAt"`
TraceId string `json:"traceId"`
}
// getExceptionRequest is the body for POST /api/exception-stack-traces/:hash.
type getExceptionRequest struct {
Pagination PaginationParams `json:"pagination"`
}
// GetExceptionResponse is the upstream ExceptionDetailResponse minus the
// session-recording blob (we don't expose recordings in v1).
type GetExceptionResponse struct {
Group *ExceptionGroup `json:"group"`
Occurrences []ExceptionStackTrace `json:"occurrences"`
Pagination Pagination `json:"pagination"`
// RelatedEntity belongs to the newest occurrence, the first of page 1.
RelatedEntity *RelatedEntity `json:"relatedEntity,omitempty"`
}
// GetException returns the group + paginated occurrences for the given hash.
func (c *Client) GetException(ctx context.Context, projectID, hash string, page PaginationParams) (*GetExceptionResponse, error) {
path := "/api/exception-stack-traces/" + url.PathEscape(hash) + "?projectId=" + url.QueryEscape(projectID)
var resp GetExceptionResponse
if err := c.do(ctx, http.MethodPost, path, getExceptionRequest{Pagination: page}, &resp); err != nil {
return nil, err
}
return &resp, nil
}
// ExceptionByIdResponse is the body of POST
// /api/exception-stack-traces/by-id/:exceptionId. Over a paginated `exceptions
// show <hash>` occurrence it adds the linked sessionId and an inline
// sessionRecording blob (passed through verbatim), and resolves directly
// without walking pages.
type ExceptionByIdResponse struct {
Exception *ExceptionStackTrace `json:"exception"`
RelatedEntity *RelatedEntity `json:"relatedEntity,omitempty"`
SessionId *uuid.UUID `json:"sessionId,omitempty"`
SessionRecording json.RawMessage `json:"sessionRecording,omitempty"`
}
// GetExceptionById returns a single exception occurrence by its id. recordedAt
// is the occurrence's recordedAt (from the URL's t= param, a notification's
// "Occurred at", or an `exceptions show` occurrence) and is required for a
// partition-pruned lookup.
func (c *Client) GetExceptionById(ctx context.Context, projectID, id string, recordedAt time.Time) (*ExceptionByIdResponse, error) {
path := "/api/exception-stack-traces/by-id/" + url.PathEscape(id) + "?projectId=" + url.QueryEscape(projectID)
var resp ExceptionByIdResponse
if err := c.do(ctx, http.MethodPost, path, recordedAtBody{RecordedAt: recordedAt}, &resp); err != nil {
return nil, err
}
return &resp, nil
}
// archiveRequest is the body for POST /api/exception-stack-traces/archive
// and .../unarchive. Same shape for both routes.
type archiveRequest struct {
Hashes []string `json:"hashes"`
}
// ArchiveExceptions marks the given exception hashes as archived for the
// project. The upstream response is just {"success": true}; on success this
// returns nil and the caller can report the count back to the user.
func (c *Client) ArchiveExceptions(ctx context.Context, projectID string, hashes []string) error {
path := "/api/exception-stack-traces/archive?projectId=" + url.QueryEscape(projectID)
return c.do(ctx, http.MethodPost, path, archiveRequest{Hashes: hashes}, nil)
}
// UnarchiveExceptions reverses ArchiveExceptions for the given hashes.
func (c *Client) UnarchiveExceptions(ctx context.Context, projectID string, hashes []string) error {
path := "/api/exception-stack-traces/unarchive?projectId=" + url.QueryEscape(projectID)
return c.do(ctx, http.MethodPost, path, archiveRequest{Hashes: hashes}, nil)
}