census.h

Go to the documentation of this file.

/*
 *
 * Copyright 2015-2016, Google Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 *     * Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above
 * copyright notice, this list of conditions and the following disclaimer
 * in the documentation and/or other materials provided with the
 * distribution.
 *     * Neither the name of Google Inc. nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */

#ifndef GRPC_CENSUS_H
#define GRPC_CENSUS_H

#include <grpc/grpc.h>

#ifdef __cplusplus
extern "C" {
#endif

enum census_features {
  CENSUS_FEATURE_NONE = 0,    
  CENSUS_FEATURE_TRACING = 1, 
  CENSUS_FEATURE_STATS = 2,   
  CENSUS_FEATURE_CPU = 4,     
  CENSUS_FEATURE_ALL =
      CENSUS_FEATURE_TRACING | CENSUS_FEATURE_STATS | CENSUS_FEATURE_CPU
};

CENSUSAPI int census_initialize(int features);
CENSUSAPI void census_shutdown(void);

CENSUSAPI int census_supported(void);

CENSUSAPI int census_enabled(void);

typedef struct census_context census_context;

typedef struct {
  const char *key;
  const char *value;
  uint8_t flags;
} census_tag;

#define CENSUS_MAX_TAG_KV_LEN 255

#define CENSUS_MAX_PROPAGATED_TAGS 255

#define CENSUS_TAG_PROPAGATE 1 
#define CENSUS_TAG_STATS 2    
#define CENSUS_TAG_RESERVED 4 
#define CENSUS_TAG_IS_PROPAGATED(flags) (flags & CENSUS_TAG_PROPAGATE)
#define CENSUS_TAG_IS_STATS(flags) (flags & CENSUS_TAG_STATS)

typedef struct {
  int n_propagated_tags; 
  int n_local_tags;      
  int n_deleted_tags;    
  int n_added_tags;      
  int n_modified_tags;   
  int n_invalid_tags;    
  int n_ignored_tags;    
} census_context_status;

CENSUSAPI census_context *census_context_create(
    const census_context *base, const census_tag *tags, int ntags,
    census_context_status const **status);

CENSUSAPI void census_context_destroy(census_context *context);

CENSUSAPI const census_context_status *census_context_get_status(
    const census_context *context);

typedef struct {
  const census_context *context;
  int base;
  int index;
  char *kvm;
} census_context_iterator;

CENSUSAPI void census_context_initialize_iterator(
    const census_context *context, census_context_iterator *iterator);

CENSUSAPI int census_context_next_tag(census_context_iterator *iterator,
                                      census_tag *tag);

CENSUSAPI int census_context_get_tag(const census_context *context,
                                     const char *key, census_tag *tag);

CENSUSAPI size_t census_context_encode(const census_context *context,
                                       char *buffer, size_t buf_size);

CENSUSAPI census_context *census_context_decode(const char *buffer,
                                                size_t size);

enum census_trace_mask_values {
  CENSUS_TRACE_MASK_NONE = 0,      
  CENSUS_TRACE_MASK_IS_SAMPLED = 1 
};

CENSUSAPI int census_trace_mask(const census_context *context);

CENSUSAPI void census_set_trace_mask(int trace_mask);

typedef struct {
  gpr_timespec ts;
} census_timestamp;

CENSUSAPI census_timestamp census_start_rpc_op_timestamp(void);

typedef struct {
  const char *(*get_rpc_service_name)(int64_t id);
  const char *(*get_rpc_method_name)(int64_t id);
} census_rpc_name_info;

CENSUSAPI census_context *census_start_client_rpc_op(
    const census_context *context, int64_t rpc_name_id,
    const census_rpc_name_info *rpc_name_info, const char *peer, int trace_mask,
    const census_timestamp *start_time);

CENSUSAPI void census_set_rpc_client_peer(census_context *context,
                                          const char *peer);

CENSUSAPI census_context *census_start_server_rpc_op(
    const char *buffer, int64_t rpc_name_id,
    const census_rpc_name_info *rpc_name_info, const char *peer, int trace_mask,
    census_timestamp *start_time);

CENSUSAPI census_context *census_start_op(census_context *context,
                                          const char *family, const char *name,
                                          int trace_mask);

CENSUSAPI void census_end_op(census_context *context, int status);

#define CENSUS_TRACE_RECORD_START_OP ((uint32_t)0)
#define CENSUS_TRACE_RECORD_END_OP ((uint32_t)1)

CENSUSAPI void census_trace_print(census_context *context, uint32_t type,
                                  const char *buffer, size_t n);

typedef struct {
  census_timestamp timestamp; 
  uint64_t trace_id;          
  uint64_t op_id;             
  uint32_t type;              
  const char *buffer;         
  size_t buf_size;            
} census_trace_record;

CENSUSAPI int census_trace_scan_start(int consume);

CENSUSAPI int census_get_trace_record(census_trace_record *trace_record);

CENSUSAPI void census_trace_scan_end();

CENSUSAPI int32_t census_define_resource(const uint8_t *resource_pb,
                                         size_t resource_pb_size);

CENSUSAPI void census_delete_resource(int32_t resource_id);

CENSUSAPI int32_t census_resource_id(const char *name);

typedef struct {
  int32_t resource_id;
  double value;
} census_value;

CENSUSAPI void census_record_values(census_context *context,
                                    census_value *values, size_t nvalues);

#ifdef __cplusplus
}
#endif

#endif /* GRPC_CENSUS_H */