1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
/*
* Copyright (C) 2019 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef ANDROID_STATS_LOG_STATS_EVENT_H
#define ANDROID_STATS_LOG_STATS_EVENT_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
/*
* Functionality to build and store the buffer sent over the statsd socket.
* This code defines and encapsulates the socket protocol.
*
* Usage:
* struct stats_event* event = stats_event_obtain();
*
* stats_event_set_atom_id(event, atomId);
* stats_event_write_int32(event, 24);
* stats_event_add_bool_annotation(event, 1, true); // annotations apply to the previous field
* stats_event_add_int32_annotation(event, 2, 128);
* stats_event_write_float(event, 2.0);
*
* stats_event_build(event);
* stats_event_write(event);
* stats_event_release(event);
*
* Notes:
* (a) write_<type>() and add_<type>_annotation() should be called in the order that fields
* and annotations are defined in the atom.
* (b) set_atom_id() can be called anytime before stats_event_write().
* (c) add_<type>_annotation() calls apply to the previous field.
* (d) If errors occur, stats_event_write() will write a bitmask of the errors to the socket.
* (e) All strings should be encoded using UTF8.
*/
/* ERRORS */
#define ERROR_NO_TIMESTAMP 0x1
#define ERROR_NO_ATOM_ID 0x2
#define ERROR_OVERFLOW 0x4
#define ERROR_ATTRIBUTION_CHAIN_TOO_LONG 0x8
#define ERROR_TOO_MANY_KEY_VALUE_PAIRS 0x10
#define ERROR_ANNOTATION_DOES_NOT_FOLLOW_FIELD 0x20
#define ERROR_INVALID_ANNOTATION_ID 0x40
#define ERROR_ANNOTATION_ID_TOO_LARGE 0x80
#define ERROR_TOO_MANY_ANNOTATIONS 0x100
#define ERROR_TOO_MANY_FIELDS 0x200
#define ERROR_INVALID_VALUE_TYPE 0x400
#define ERROR_STRING_NOT_NULL_TERMINATED 0x800
/* TYPE IDS */
#define INT32_TYPE 0x00
#define INT64_TYPE 0x01
#define STRING_TYPE 0x02
#define LIST_TYPE 0x03
#define FLOAT_TYPE 0x04
#define BOOL_TYPE 0x05
#define BYTE_ARRAY_TYPE 0x06
#define OBJECT_TYPE 0x07
#define KEY_VALUE_PAIRS_TYPE 0x08
#define ATTRIBUTION_CHAIN_TYPE 0x09
#define ERROR_TYPE 0x0F
#ifdef __cplusplus
extern "C" {
#endif // __CPLUSPLUS
struct stats_event;
/* SYSTEM API */
struct stats_event* stats_event_obtain();
// The build function can be called multiple times without error. If the event
// has been built before, this function is a no-op.
void stats_event_build(struct stats_event* event);
int stats_event_write(struct stats_event* event);
void stats_event_release(struct stats_event* event);
void stats_event_set_atom_id(struct stats_event* event, uint32_t atomId);
void stats_event_write_int32(struct stats_event* event, int32_t value);
void stats_event_write_int64(struct stats_event* event, int64_t value);
void stats_event_write_float(struct stats_event* event, float value);
void stats_event_write_bool(struct stats_event* event, bool value);
void stats_event_write_byte_array(struct stats_event* event, const uint8_t* buf, size_t numBytes);
// Buf must be null-terminated.
void stats_event_write_string8(struct stats_event* event, const char* value);
// Tags must be null-terminated.
void stats_event_write_attribution_chain(struct stats_event* event, const uint32_t* uids,
const char* const* tags, uint8_t numNodes);
/* key_value_pair struct can be constructed as follows:
* struct key_value_pair pair = {.key = key, .valueType = STRING_TYPE,
* .stringValue = buf};
*/
struct key_value_pair {
int32_t key;
uint8_t valueType; // expected to be INT32_TYPE, INT64_TYPE, FLOAT_TYPE, or STRING_TYPE
union {
int32_t int32Value;
int64_t int64Value;
float floatValue;
const char* stringValue; // must be null terminated
};
};
void stats_event_write_key_value_pairs(struct stats_event* event, struct key_value_pair* pairs,
uint8_t numPairs);
void stats_event_add_bool_annotation(struct stats_event* event, uint8_t annotationId, bool value);
void stats_event_add_int32_annotation(struct stats_event* event, uint8_t annotationId,
int32_t value);
uint32_t stats_event_get_atom_id(struct stats_event* event);
// Size is an output parameter.
uint8_t* stats_event_get_buffer(struct stats_event* event, size_t* size);
uint32_t stats_event_get_errors(struct stats_event* event);
// This table is used by StatsEventCompat to access the stats_event API.
struct stats_event_api_table {
struct stats_event* (*obtain)(void);
void (*build)(struct stats_event*);
int (*write)(struct stats_event*);
void (*release)(struct stats_event*);
void (*set_atom_id)(struct stats_event*, uint32_t);
void (*write_int32)(struct stats_event*, int32_t);
void (*write_int64)(struct stats_event*, int64_t);
void (*write_float)(struct stats_event*, float);
void (*write_bool)(struct stats_event*, bool);
void (*write_byte_array)(struct stats_event*, const uint8_t*, size_t);
void (*write_string8)(struct stats_event*, const char*);
void (*write_attribution_chain)(struct stats_event*, const uint32_t*, const char* const*,
uint8_t);
void (*write_key_value_pairs)(struct stats_event*, struct key_value_pair*, uint8_t);
void (*add_bool_annotation)(struct stats_event*, uint8_t, bool);
void (*add_int32_annotation)(struct stats_event*, uint8_t, int32_t);
uint32_t (*get_atom_id)(struct stats_event*);
uint8_t* (*get_buffer)(struct stats_event*, size_t*);
uint32_t (*get_errors)(struct stats_event*);
};
// exposed for benchmarking only
void stats_event_truncate_buffer(struct stats_event* event, bool truncate);
#ifdef __cplusplus
}
#endif // __CPLUSPLUS
#endif // ANDROID_STATS_LOG_STATS_EVENT_H
|
