Documentation
¶
Overview ¶
Package api contains structures and data-type definitions that could be used for accessing the Logrange database using the api.Client interface.
This is version v0 of the api and the following rules must be obeyed when a change is needed:
- Names of existing data-types cannot be changed
- Names of struct fields must be capitalized and cannot be changed
- Types of already existing fields cannot be changed
- Functions params and signatures cannot be changed.
- New fields could be added to the existing data structures
- New types and structures could be added
- New functions could be added either to existing interfaces or to the package
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Select ¶
func Select(ctx context.Context, querirer Querier, qr *QueryRequest, streamMode bool, handler func(res *QueryResult)) error
Select is a helper function which allows to perform one or many requests to the server. The function supports 2 modes - limited select and stream mode, that are controlled by streamMode flag
The limited select is used when streamMode=false. In this mode Select will return requested number of records, or all records whatever is less. The limit must be explicitly set in qr.Limit param, which will overwrite value specified in qr.Query
In stream mode records will be read until the Select is interrupted. So the number of records in the result is not limited at all. In stream mode qr.Limit is used as a parameter for reading the number of records in one batch request. So the value should not be big (hundreds or thousands records). When the end of result stream is reached, the function will not be over, but it continues to read records using qr.WaitTimeout value for waiting the new records. In stream mode the function is over only when context is closed or an error happens while the query is executed.
The results of read operations will be passed to the handler, a call-back function. Select will call handler any time when it could make a query to the server and there is no communication errors
The function returns error if the query was unsuccessful by any reason.
Types ¶
type Admin ¶
type Admin interface {
// Execute runs the lql query on the server and provides the execution result
// in text form or an error, if the query could not be run. Not all LQL queries
// could be support
Execute(ctx context.Context, req ExecRequest) (ExecResult, error)
}
Admin interface allows to perform some administrative operations. The Execute function accepts a LQL statement and it returns the server response in the result. For 'SELECT' statement please use Querier interface instead of the Execute function.
type Client ¶
type Client interface {
Querier
Ingestor
Admin
Pipes
// Close allows to close connection to the server and to free all resources
Close() error
}
Client interface provides all api functionality in one interface.
type ExecRequest ¶
type ExecRequest struct {
// Query contains a LQL statement to be executed
Query string
}
ExecRequest struct must be provided as an input for Admin.Execute request
type ExecResult ¶
type ExecResult struct {
// Output contains formatted output result of the command execution
Output string
// Err contains the operation error, if any
Err error `json:"-"`
}
ExecResult struct is used as a response of the request to execute a LQL query
type Ingestor ¶
type Ingestor interface {
// Write sends events into the partition identified by tags provided. It expects a slice of events and
// LogEvent(s) and a pointer to the WriteResult. 'Tags' and 'Fields' fields in LogEvents
// are ignored during the writing operation, but tags and fields params will be applied to all of the events.
//
// The function returns error if any communication problem to the server happens.
// If the Write operation could reach the server, but the operation was failed there by any
// reason, the res variable will contain the error result from server (res.Err)
Write(ctx context.Context, tags, fields string, evs []*LogEvent, res *WriteResult) error
}
Ingestor provides Write method for sending records into a partition.
type LogEvent ¶
type LogEvent struct {
// Timestamp contains the time-stamp for the message. It contains a timestamp,
// associated with the event, in nano-seconds
Timestamp int64
// Message contains the event data
Message string
// Tag line associated with the event. It could be empty when the new records ingested
// (write operation). The tag line has the form like `tag1=value1,tag2=value2...`
Tags string
// Fields associated with the event. The field could be empty.
// The fields line has the form like `field1=value1,field2=value2...`
Fields string
}
LogEvent struct describes a partition record.
type Pipe ¶
type Pipe struct {
// Name contains the pipe name, which must be unique
Name string
// TagsCond contains the condition, which filters sources for the pipe
TagsCond string
// FilterCond desribes the filtering condition. Only events, for which the condition
// is true, will be piped
FilterCond string
// Destination contains tags conditions used for the pipe destination. This field is
// defined by server, so it is ignored by Pipes.EnsurePipe
Destination string
}
Pipe struct describes a pipe
type PipeCreateResult ¶
type PipeCreateResult struct {
// Pipe contains created pipe object
Pipe Pipe
// Err the operaion error, if any.
Err error `json:"-"`
}
PipeCreateResult struct describes the result of Pipes.EnsurePipe function
type Pipes ¶
type Pipes interface {
// Create a new pipe if it doesn't exist. The function will return an error,
// if the function could not connet or reach the server by any reason. If the communiction
// was ok, but the operation was failed on the server side by any reason, the function
// will return nil, but res.Err will contain the server error.
EnsurePipe(ctx context.Context, p Pipe, res *PipeCreateResult) error
}
Pipes allows to manage streams
type Querier ¶
type Querier interface {
// Query runs lql to collect the server data and returns it in the QueryResult.
// It returns an error which indicates that the query could not be delivered to
// the server. If there is no communication problems, but server could not perform
// the query by any reason, the function will return nil, but the server error could
// be found in res.Err
//
// The Query expects res param, where the Query result will be placed (see QueryResult).
// The QueryResult contains the data, which is read and the NextQueryRequest field
// which value may be used for consecutive read requests. Using res.NextQueryRequest allows
// to improve the read performance. Also the res.NextQueryRequest.Pos contains the next
// record read position, which could be used for iterating over the result record collection.
Query(ctx context.Context, req *QueryRequest, res *QueryResult) error
}
Querier interface allows to perform read operations.
type QueryRequest ¶
type QueryRequest struct {
// ReqId identifies the request Id on server side. The field should not be populated by client in
// its first request, but it can be taken from QueryResult.NextQueryRequest for consecutive
// requests.
//
// The field is helpful when records should be read in order by several consecutive reaquests.
// Server could cache some resources to perform the iteration quickly. So the server could return
// a value in QueryResult.NextQueryRequest field, which could be provided with the following request.
ReqId uint64
// Query contains SELECT statement for reading records. This field contains the request, but
// some parameters like POSTION, OFFSET and LIMIT could be overwritten by fields from the QueryResult
Query string
// Pos contains the next read record position. For consecutive batch reading the value
// can be taken from the previous request result QueryResult.NextQueryRequest
Pos string
// WaitTimeout in seconds provide waiting new data timeout in case of the request starts from
// the end of result stream (no records). The timout cannot exceed 60 seconds. When the timeout
// expires and no data is arrived response with no data will be returned.
WaitTimeout int
// Offset contains the offset from the current position (either positive or negative). For
// batch read it should be set to 0 for non-first request.
Offset int
// Limit defines the maximum number of records which could be read from the sources
Limit int
}
QueryRequest struct describes a request for reading records
func (*QueryRequest) String ¶
func (qr *QueryRequest) String() string
String is part of Stringify interface
type QueryResult ¶
type QueryResult struct {
// Events slice contains the result of the query execution
Events []*LogEvent
// NextQueryRequest contains the query for reading next porition of events. It makes sense only if Err is
// nil.
NextQueryRequest QueryRequest
// Err the operation error. If the Err is nil, the operation successfully executed
Err error `json:"-"`
}
QeryResult struct contains the result returned by the server in a response on LQL execution (see Querier.Query)
func (*QueryResult) String ¶
func (qres *QueryResult) String() string
String is part of Stringify interface
type WriteResult ¶
type WriteResult struct {
// Err contains the error which happens on the server side. So the Ingestor.Write
// call could be successful (no error is returned), but the Err field in res parameter
// (see Ingestor.Write) wil be not nil. The error from the server is here.
Err error
}
WriteResult struct contains result of Ingestor.Write operation execution.
Source Files
Directories