diff options
author | rghetia <rghetia@yahoo.com> | 2018-06-21 22:01:16 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-06-21 22:01:16 -0700 |
commit | bc143adc32e6db5e158485246d8d3aa6592b1cff (patch) | |
tree | 40b492607f5be764ad4f0a00163dfe61abf4d5ef /api/src/main | |
parent | 9437d455d8a6982abfaec9c7ca162693b0f23c4f (diff) | |
download | opencensus-java-bc143adc32e6db5e158485246d8d3aa6592b1cff.tar.gz |
Summary Span: Add encoder/decoder for Server Stats. (#1272)
* Summary Span: Add encoder/decoder for Server Stats.
* Fixed build errors reported by Kokoro/Travis.
* Fixed review comments.
- Added missing javadoc annotation.
- included version in encoder/decoder.
- renamed get methods for ServerStats.
* Change version from 0.15 to 0.16
- also fixed CURRENT_VERSION for encoder/decoder and added test for it.
* Make ServerStatsEncoding public.
* Add Test ServerStatsFieldEnum.Size
replace traceOption() wiht getTraceOption()
Diffstat (limited to 'api/src/main')
4 files changed, 415 insertions, 0 deletions
diff --git a/api/src/main/java/io/opencensus/common/ServerStats.java b/api/src/main/java/io/opencensus/common/ServerStats.java new file mode 100644 index 00000000..42efa1f2 --- /dev/null +++ b/api/src/main/java/io/opencensus/common/ServerStats.java @@ -0,0 +1,86 @@ +/* + * Copyright 2018, OpenCensus Authors + * + * 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. + */ + +package io.opencensus.common; + +import com.google.auto.value.AutoValue; +import javax.annotation.concurrent.Immutable; + +/** + * A representation of stats measured on the server side. + * + * @since 0.16 + */ +@Immutable +@AutoValue +public abstract class ServerStats { + + ServerStats() {} + + /** + * Returns Load Balancer latency, a latency observed at Load Balancer. + * + * @return Load Balancer latency in nanoseconds. + * @since 0.16 + */ + public abstract long getLbLatencyNs(); + + /** + * Returns Service latency, a latency observed at Server. + * + * @return Service latency in nanoseconds. + * @since 0.16 + */ + public abstract long getServiceLatencyNs(); + + /** + * Returns Trace options, a set of bits indicating properties of trace. + * + * @return Trace options a set of bits indicating properties of trace. + * @since 0.16 + */ + public abstract byte getTraceOption(); + + /** + * Creates new {@link ServerStats} from specified parameters. + * + * @param lbLatencyNs Represents request processing latency observed on Load Balancer. It is + * measured in nanoseconds. Must not be less than 0. Value of 0 represents that the latency is + * not measured. + * @param serviceLatencyNs Represents request processing latency observed on Server. It is + * measured in nanoseconds. Must not be less than 0. Value of 0 represents that the latency is + * not measured. + * @param traceOption Represents set of bits to indicate properties of trace. Currently it used + * only the least signification bit to represent sampling of the request on the server side. + * Other bits are ignored. + * @return new {@code ServerStats} with specified fields. + * @throws IllegalArgumentException if the arguments are out of range. + * @since 0.16 + */ + public static ServerStats create(long lbLatencyNs, long serviceLatencyNs, byte traceOption) { + + if (lbLatencyNs < 0) { + throw new IllegalArgumentException("'getLbLatencyNs' is less than zero: " + lbLatencyNs); + } + + if (serviceLatencyNs < 0) { + throw new IllegalArgumentException( + "'getServiceLatencyNs' is less than zero: " + serviceLatencyNs); + } + + return new AutoValue_ServerStats(lbLatencyNs, serviceLatencyNs, traceOption); + } +} diff --git a/api/src/main/java/io/opencensus/common/ServerStatsDeserializationException.java b/api/src/main/java/io/opencensus/common/ServerStatsDeserializationException.java new file mode 100644 index 00000000..2332733c --- /dev/null +++ b/api/src/main/java/io/opencensus/common/ServerStatsDeserializationException.java @@ -0,0 +1,47 @@ +/* + * Copyright 2018, OpenCensus Authors + * + * 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. + */ + +package io.opencensus.common; + +/** + * Exception thrown when a {@link ServerStats} cannot be parsed. + * + * @since 0.16 + */ +public final class ServerStatsDeserializationException extends Exception { + private static final long serialVersionUID = 0L; + + /** + * Constructs a new {@code ServerStatsDeserializationException} with the given message. + * + * @param message a message describing the error. + * @since 0.16 + */ + public ServerStatsDeserializationException(String message) { + super(message); + } + + /** + * Constructs a new {@code ServerStatsDeserializationException} with the given message and cause. + * + * @param message a message describing the error. + * @param cause the cause of the error. + * @since 0.16 + */ + public ServerStatsDeserializationException(String message, Throwable cause) { + super(message, cause); + } +} diff --git a/api/src/main/java/io/opencensus/common/ServerStatsEncoding.java b/api/src/main/java/io/opencensus/common/ServerStatsEncoding.java new file mode 100644 index 00000000..024a93f8 --- /dev/null +++ b/api/src/main/java/io/opencensus/common/ServerStatsEncoding.java @@ -0,0 +1,125 @@ +/* + * Copyright 2018, OpenCensus Authors + * + * 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. + */ + +package io.opencensus.common; + +import java.nio.ByteBuffer; +import java.nio.ByteOrder; + +/** + * A service class to encode/decode {@link ServerStats} as defined by the spec. + * + * <p>See <a + * href="https://github.com/census-instrumentation/opencensus-specs/blob/master/encodings/CensusServerStatsEncoding.md">opencensus-server-stats-specs</a> + * for encoding {@code ServerStats} + * + * <p>Use {@code ServerStatsEncoding.toBytes(ServerStats stats)} to encode. + * + * <p>Use {@code ServerStatsEncoding.parseBytes(byte[] serialized)} to decode. + * + * @since 0.16 + */ +public final class ServerStatsEncoding { + + private ServerStatsEncoding() {} + + /** + * The current encoding version. The value is {@value #CURRENT_VERSION} + * + * @since 0.16 + */ + public static final byte CURRENT_VERSION = (byte) 0; + + /** + * Encodes the {@link ServerStats} as per the Opencensus Summary Span specification. + * + * @param stats {@code ServerStats} to encode. + * @return encoded byte array. + * @since 0.16 + */ + public static byte[] toBytes(ServerStats stats) { + // Should this be optimized to not include invalid values? + + ByteBuffer bb = ByteBuffer.allocate(ServerStatsFieldEnums.getTotalSize() + 1); + bb.order(ByteOrder.LITTLE_ENDIAN); + + // put version + bb.put(CURRENT_VERSION); + + bb.put((byte) ServerStatsFieldEnums.Id.SERVER_STATS_LB_LATENCY_ID.value()); + bb.putLong(stats.getLbLatencyNs()); + + bb.put((byte) ServerStatsFieldEnums.Id.SERVER_STATS_SERVICE_LATENCY_ID.value()); + bb.putLong(stats.getServiceLatencyNs()); + + bb.put((byte) ServerStatsFieldEnums.Id.SERVER_STATS_TRACE_OPTION_ID.value()); + bb.put(stats.getTraceOption()); + return bb.array(); + } + + /** + * Decodes serialized byte array to create {@link ServerStats} as per Opencensus Summary Span + * specification. + * + * @param serialized encoded {@code ServerStats} in byte array. + * @return decoded {@code ServerStats}. null if decoding fails. + * @since 0.16 + */ + public static ServerStats parseBytes(byte[] serialized) + throws ServerStatsDeserializationException { + final ByteBuffer bb = ByteBuffer.wrap(serialized); + bb.order(ByteOrder.LITTLE_ENDIAN); + long serviceLatencyNs = 0L; + long lbLatencyNs = 0L; + byte traceOption = (byte) 0; + + // Check the version first. + if (!bb.hasRemaining()) { + throw new ServerStatsDeserializationException("Serialized ServerStats buffer is empty"); + } + byte version = bb.get(); + + if (version > CURRENT_VERSION || version < 0) { + throw new ServerStatsDeserializationException("Invalid ServerStats version: " + version); + } + + while (bb.hasRemaining()) { + ServerStatsFieldEnums.Id id = ServerStatsFieldEnums.Id.valueOf((int) bb.get() & 0xFF); + if (id == null) { + // Skip remaining; + bb.position(bb.limit()); + } else { + switch (id) { + case SERVER_STATS_LB_LATENCY_ID: + lbLatencyNs = bb.getLong(); + break; + case SERVER_STATS_SERVICE_LATENCY_ID: + serviceLatencyNs = bb.getLong(); + break; + case SERVER_STATS_TRACE_OPTION_ID: + traceOption = bb.get(); + break; + } + } + } + try { + return ServerStats.create(lbLatencyNs, serviceLatencyNs, traceOption); + } catch (IllegalArgumentException e) { + throw new ServerStatsDeserializationException( + "Serialized ServiceStats contains invalid values: " + e.getMessage()); + } + } +} diff --git a/api/src/main/java/io/opencensus/common/ServerStatsFieldEnums.java b/api/src/main/java/io/opencensus/common/ServerStatsFieldEnums.java new file mode 100644 index 00000000..92194d96 --- /dev/null +++ b/api/src/main/java/io/opencensus/common/ServerStatsFieldEnums.java @@ -0,0 +1,157 @@ +/* + * Copyright 2018, OpenCensus Authors + * + * 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. + */ + +package io.opencensus.common; + +import java.util.TreeMap; + +/** + * A Enum representation for Ids and Size for attributes of {@code ServerStats}. + * + * <p>See <a + * href="https://github.com/census-instrumentation/opencensus-specs/blob/master/encodings/CensusServerStatsEncoding.md">opencensus-server-stats-specs</a> + * for the field ids and their length defined for Server Stats + * + * @since 0.16 + */ +public final class ServerStatsFieldEnums { + + /** + * Available Ids for {@code ServerStats} attributes. + * + * @since 0.16 + */ + public enum Id { + /** + * Id for Latency observed at Load Balancer. + * + * @since 0.16 + */ + SERVER_STATS_LB_LATENCY_ID(0), + /** + * Id for Latency observed at Server. + * + * @since 0.16 + */ + SERVER_STATS_SERVICE_LATENCY_ID(1), + /** + * Id for Trace options. + * + * @since 0.16 + */ + SERVER_STATS_TRACE_OPTION_ID(2); + + private final int value; + + private Id(int value) { + this.value = value; + } + + /** + * Returns the numerical value of the {@link Id}. + * + * @return the numerical value of the {@code Id}. + * @since 0.16 + */ + public int value() { + return value; + } + + private static final TreeMap<Integer, Id> map = new TreeMap<Integer, Id>(); + + static { + for (Id id : Id.values()) { + map.put(id.value, id); + } + } + + /** + * Returns the {@link Id} representing the value value of the id. + * + * @param value integer value for which {@code Id} is being requested. + * @return the numerical value of the id. null if the id is not valid + * @since 0.16 + */ + public static Id valueOf(int value) { + return (Id) map.get(value); + } + } + + /** + * Size for each attributes in {@code ServerStats}. + * + * @since 0.16 + */ + public enum Size { + /** + * Number of bytes used to represent latency observed at Load Balancer + * + * @since 0.16 + */ + SERVER_STATS_LB_LATENCY_SIZE(8), + /** + * Number of bytes used to represent latency observed at Server + * + * @since 0.16 + */ + SERVER_STATS_SERVICE_LATENCY_SIZE(8), + /** + * Number of bytes used to represent Trace option + * + * @since 0.16 + */ + SERVER_STATS_TRACE_OPTION_SIZE(1); + + private final int value; + + private Size(int value) { + this.value = value; + } + + /** + * Returns the numerical value of the {@link Size}. + * + * @return the numerical value of the {@code Size}. + * @since 0.16 + */ + public int value() { + return value; + } + } + + private static final int TOTALSIZE = computeTotalSize(); + + private ServerStatsFieldEnums() {} + + private static int computeTotalSize() { + int sum = 0; + for (Size sizeValue : Size.values()) { + sum += sizeValue.value(); + sum += 1; // For Id + } + return sum; + } + + /** + * Returns the total size required to encode the {@code ServerStats} + * + * @return the total size required to encode all fields in {@code ServerStats}. + * @since 0.16 + */ + public static int getTotalSize() { + return TOTALSIZE; + } +} |