From b04afe0901c9205882cfaa91bf644550fbea291c Mon Sep 17 00:00:00 2001 From: sureshbabu-areekara Date: Mon, 17 Feb 2025 14:40:21 +0530 Subject: [PATCH] Review comments. Review comments. --- .../internal/tls/DistinguishedNameParser.java | 271 +++++++----------- .../internal/tls/LegacyHostnameVerifier.java | 96 ++----- .../presto/common/TelemetryConfig.java | 57 +--- .../facebook/presto/common/TracingConfig.java | 7 +- .../java/com/facebook/presto/Session.java | 9 +- .../presto/telemetry/TelemetryModule.java | 3 - .../presto/telemetry/TelemetryResource.java | 2 +- .../telemetry/TelemetryTracingImpl.java | 8 +- .../presto/telemetry/TracingManager.java | 175 +---------- .../OpenTelemetryTracingImpl.java | 77 ++--- .../opentelemetry/TextMapGetterImpl.java | 3 - .../tracing/OpenTelemetryFactoryImpl.java | 2 +- .../opentelemetry/tracing/ScopedSpan.java | 3 +- .../opentelemetry/tracing/TracingSpan.java | 3 +- .../opentelemetry/OpenTelemetryPlugin.java | 3 - .../presto/spi/telemetry/BaseSpan.java | 5 +- .../spi/telemetry/TelemetryFactory.java | 12 +- .../spi/telemetry/TelemetryTracing.java | 54 ++-- 18 files changed, 205 insertions(+), 585 deletions(-) diff --git a/presto-client/src/main/java/com/facebook/presto/client/okhttp3/internal/tls/DistinguishedNameParser.java b/presto-client/src/main/java/com/facebook/presto/client/okhttp3/internal/tls/DistinguishedNameParser.java index 65bd1faf03840..e1974fed71eff 100644 --- a/presto-client/src/main/java/com/facebook/presto/client/okhttp3/internal/tls/DistinguishedNameParser.java +++ b/presto-client/src/main/java/com/facebook/presto/client/okhttp3/internal/tls/DistinguishedNameParser.java @@ -23,225 +23,191 @@ final class DistinguishedNameParser { private final String dn; private final int length; - private int pos; - private int beg; + private int position; + private int start; private int end; - - /** - * Temporary variable to store positions of the currently parsed item. - */ private int cur; + private char[] chars; /** - * Distinguished name characters. + * Instantiates a new Distinguished name parser. + * + * @param principal the principal */ - private char[] chars; - DistinguishedNameParser(X500Principal principal) { - // RFC2253 is used to ensure we get attributes in the reverse - // order of the underlying ASN.1 encoding, so that the most - // significant values of repeated attributes occur first. this.dn = principal.getName(X500Principal.RFC2253); this.length = this.dn.length(); } - // gets next attribute type: (ALPHA 1*keychar) / oid - private String nextAT() + private String nextAttributeType() { - for (; pos < length && chars[pos] == ' '; pos++) { - // skip preceding space chars, they can present after - // comma or semicolon (compatibility with RFC 1779) + while (position < length && chars[position] == ' ') { + position++; } - if (pos == length) { - return null; // reached the end of DN + if (position == length) { + return null; } - // mark the beginning of attribute type - beg = pos; + start = position; - // attribute type chars - pos++; - for (; pos < length && chars[pos] != '=' && chars[pos] != ' '; pos++) { - // we don't follow exact BNF syntax here: - // accept any char except space and '=' + position++; + while (position < length && chars[position] != '=' && chars[position] != ' ') { + position++; } - if (pos >= length) { + if (position >= length) { throw new IllegalStateException("Unexpected end of DN: " + dn); } - // mark the end of attribute type - end = pos; + end = position; - if (chars[pos] == ' ') { - for (; pos < length && chars[pos] != '=' && chars[pos] == ' '; pos++) { - // skip trailing space chars between attribute type and '=' - // (compatibility with RFC 1779) + if (chars[position] == ' ') { + while (position < length && chars[position] != '=' && chars[position] == ' ') { + position++; } - if (chars[pos] != '=' || pos == length) { + if (chars[position] != '=' || position == length) { throw new IllegalStateException("Unexpected end of DN: " + dn); } } - pos++; //skip '=' char + position++; - for (; pos < length && chars[pos] == ' '; pos++) { - // skip space chars between '=' and attribute value - // (compatibility with RFC 1779) + while (position < length && chars[position] == ' ') { + position++; } - // in case of oid attribute type skip its prefix: "oid." or "OID." - // (compatibility with RFC 1779) - if ((end - beg > 4) && (chars[beg + 3] == '.') - && (chars[beg] == 'O' || chars[beg] == 'o') - && (chars[beg + 1] == 'I' || chars[beg + 1] == 'i') - && (chars[beg + 2] == 'D' || chars[beg + 2] == 'd')) { - beg += 4; + if ((end - start > 4) && (chars[start + 3] == '.') + && (chars[start] == 'O' || chars[start] == 'o') + && (chars[start + 1] == 'I' || chars[start + 1] == 'i') + && (chars[start + 2] == 'D' || chars[start + 2] == 'd')) { + start += 4; } - return new String(chars, beg, end - beg); + return new String(chars, start, end - start); } - // gets quoted attribute value: QUOTATION *( quotechar / pair ) QUOTATION - private String quotedAV() + private String quotedAttributeValue() { - pos++; - beg = pos; - end = beg; + position++; + start = position; + end = start; while (true) { - if (pos == length) { + if (position == length) { throw new IllegalStateException("Unexpected end of DN: " + dn); } - if (chars[pos] == '"') { - // enclosing quotation was found - pos++; + if (chars[position] == '"') { + position++; break; } - else if (chars[pos] == '\\') { + else if (chars[position] == '\\') { chars[end] = getEscaped(); } else { - // shift char: required for string with escaped chars - chars[end] = chars[pos]; + chars[end] = chars[position]; } - pos++; + position++; end++; } - for (; pos < length && chars[pos] == ' '; pos++) { - // skip trailing space chars before comma or semicolon. - // (compatibility with RFC 1779) + while (position < length && chars[position] == ' ') { + position++; } - return new String(chars, beg, end - beg); + return new String(chars, start, end - start); } - // gets hex string attribute value: "#" hexstring - private String hexAV() + private String hexAttributeValue() { - if (pos + 4 >= length) { - // encoded byte array must be not less then 4 c + if (position + 4 >= length) { throw new IllegalStateException("Unexpected end of DN: " + dn); } - beg = pos; // store '#' position - pos++; + start = position; + position++; while (true) { - // check for end of attribute value - // looks for space and component separators - if (pos == length || chars[pos] == '+' || chars[pos] == ',' - || chars[pos] == ';') { - end = pos; + if (position == length || chars[position] == '+' || chars[position] == ',' + || chars[position] == ';') { + end = position; break; } - if (chars[pos] == ' ') { - end = pos; - pos++; - for (; pos < length && chars[pos] == ' '; pos++) { - // skip trailing space chars before comma or semicolon. - // (compatibility with RFC 1779) + if (chars[position] == ' ') { + end = position; + position++; + while (position < length && chars[position] == ' ') { + position++; } break; } - else if (chars[pos] >= 'A' && chars[pos] <= 'F') { - chars[pos] += 32; //to low case + else if (chars[position] >= 'A' && chars[position] <= 'F') { + chars[position] += 32; } - pos++; + position++; } - // verify length of hex string - // encoded byte array must be not less then 4 and must be even number - int hexLen = end - beg; // skip first '#' char + int hexLen = end - start; if (hexLen < 5 || (hexLen & 1) == 0) { throw new IllegalStateException("Unexpected end of DN: " + dn); } - // get byte encoding from string representation byte[] encoded = new byte[hexLen / 2]; - for (int i = 0, p = beg + 1; i < encoded.length; p += 2, i++) { + for (int i = 0, p = start + 1; i < encoded.length; p += 2, i++) { encoded[i] = (byte) getByte(p); } - return new String(chars, beg, hexLen); + return new String(chars, start, hexLen); } - // gets string attribute value: *( stringchar / pair) - private String escapedAV() + + private String escapedAttributeValue() { - beg = pos; - end = pos; + start = position; + end = position; while (true) { - if (pos >= length) { - // the end of DN has been found - return new String(chars, beg, end - beg); + if (position >= length) { + return new String(chars, start, end - start); } - switch (chars[pos]) { + switch (chars[position]) { case '+': case ',': case ';': - // separator char has been found - return new String(chars, beg, end - beg); + return new String(chars, start, end - start); case '\\': - // escaped char chars[end++] = getEscaped(); - pos++; + position++; break; case ' ': - // need to figure out whether space defines - // the end of attribute value or not cur = end; - pos++; + position++; chars[end++] = ' '; - for (; pos < length && chars[pos] == ' '; pos++) { + while (position < length && chars[position] == ' ') { chars[end++] = ' '; + position++; } - if (pos == length || chars[pos] == ',' || chars[pos] == '+' - || chars[pos] == ';') { - // separator char or the end of DN has been found - return new String(chars, beg, cur - beg); + if (position == length || chars[position] == ',' || chars[position] == '+' + || chars[position] == ';') { + return new String(chars, start, cur - start); } break; default: - chars[end++] = chars[pos]; - pos++; + chars[end++] = chars[position]; + position++; } } } - // returns escaped char private char getEscaped() { - pos++; - if (pos == length) { + position++; + if (position == length) { throw new IllegalStateException("Unexpected end of DN: " + dn); } - switch (chars[pos]) { + switch (chars[position]) { case '"': case '\\': case ',': @@ -255,51 +221,46 @@ private char getEscaped() case '*': case '%': case '_': - //FIXME: escaping is allowed only for leading or trailing space char - return chars[pos]; + return chars[position]; default: - // RFC doesn't explicitly say that escaped hex pair is - // interpreted as UTF-8 char. It only contains an example of such DN. return getUTF8(); } } - // decodes UTF-8 char - // see http://www.unicode.org for UTF-8 bit distribution table private char getUTF8() { - int res = getByte(pos); - pos++; //FIXME tmp + int res = getByte(position); + position++; - if (res < 128) { // one byte: 0-7F + if (res < 128) { return (char) res; } else if (res >= 192 && res <= 247) { int count; - if (res <= 223) { // two bytes: C0-DF + if (res <= 223) { count = 1; res = res & 0x1F; } - else if (res <= 239) { // three bytes: E0-EF + else if (res <= 239) { count = 2; res = res & 0x0F; } - else { // four bytes: F0-F7 + else { count = 3; res = res & 0x07; } int b; for (int i = 0; i < count; i++) { - pos++; - if (pos == length || chars[pos] != '\\') { - return 0x3F; //FIXME failed to decode UTF-8 char - return '?' + position++; + if (position == length || chars[position] != '\\') { + return 0x3F; } - pos++; + position++; - b = getByte(pos); - pos++; //FIXME tmp + b = getByte(position); + position++; if ((b & 0xC0) != 0x80) { - return 0x3F; //FIXME failed to decode UTF-8 char - return '?' + return 0x3F; } res = (res << 6) + (b & 0x3F); @@ -307,16 +268,10 @@ else if (res <= 239) { // three bytes: E0-EF return (char) res; } else { - return 0x3F; //FIXME failed to decode UTF-8 char - return '?' + return 0x3F; } } - // Returns byte representation of a char pair - // The char pair is composed of DN char in - // specified 'position' and the next char - // According to BNF syntax: - // hexchar = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" - // / "a" / "b" / "c" / "d" / "e" / "f" private int getByte(int position) { if (position + 1 >= length) { @@ -361,59 +316,55 @@ else if (b2 >= 'A' && b2 <= 'F') { * if none found. * * @param attributeType attribute type to look for (e.g. "ca") + * @return the string */ public String findMostSpecific(String attributeType) { - // Initialize internal state. - pos = 0; - beg = 0; + position = 0; + start = 0; end = 0; cur = 0; chars = dn.toCharArray(); - String attType = nextAT(); + String attType = nextAttributeType(); if (attType == null) { return null; } while (true) { String attValue = ""; - if (pos == length) { + if (position == length) { return null; } - switch (chars[pos]) { + switch (chars[position]) { case '"': - attValue = quotedAV(); + attValue = quotedAttributeValue(); break; case '#': - attValue = hexAV(); + attValue = hexAttributeValue(); break; case '+': case ',': - case ';': // compatibility with RFC 1779: semicolon can separate RDNs - //empty attribute value + case ';': break; default: - attValue = escapedAV(); + attValue = escapedAttributeValue(); } - // Values are ordered from most specific to least specific - // due to the RFC2253 formatting. So take the first match - // we see. if (attributeType.equalsIgnoreCase(attType)) { return attValue; } - if (pos >= length) { + if (position >= length) { return null; } - if (chars[pos] == ',' || chars[pos] == ';') { + if (chars[position] == ',' || chars[position] == ';') { //Do nothing - } else if (chars[pos] != '+') { + } else if (chars[position] != '+') { throw new IllegalStateException("Malformed DN: " + dn); } - pos++; - attType = nextAT(); + position++; + attType = nextAttributeType(); if (attType == null) { throw new IllegalStateException("Malformed DN: " + dn); } diff --git a/presto-client/src/main/java/com/facebook/presto/client/okhttp3/internal/tls/LegacyHostnameVerifier.java b/presto-client/src/main/java/com/facebook/presto/client/okhttp3/internal/tls/LegacyHostnameVerifier.java index 79aa87506ec89..34eb27fa6c56c 100644 --- a/presto-client/src/main/java/com/facebook/presto/client/okhttp3/internal/tls/LegacyHostnameVerifier.java +++ b/presto-client/src/main/java/com/facebook/presto/client/okhttp3/internal/tls/LegacyHostnameVerifier.java @@ -30,6 +30,9 @@ import java.util.Locale; import java.util.regex.Pattern; +/** + * The type Legacy hostname verifier. + */ public class LegacyHostnameVerifier implements HostnameVerifier { @@ -38,6 +41,9 @@ public class LegacyHostnameVerifier private static final Pattern VERIFY_AS_IP_ADDRESS = Pattern.compile( "([0-9a-fA-F]*:[0-9a-fA-F:.]*)|([\\d.]+)"); + /** + * The constant INSTANCE. + */ public static final HostnameVerifier INSTANCE = new LegacyHostnameVerifier(); private LegacyHostnameVerifier() @@ -51,23 +57,19 @@ public boolean verify(String host, SSLSession session) return true; } - // the CN cannot be used with IP addresses if (verifyAsIpAddress(host)) { return false; } - // try to verify using the legacy CN rules try { Certificate[] certificates = session.getPeerCertificates(); X509Certificate certificate = (X509Certificate) certificates[0]; - // only use CN if there are no alt names if (!allSubjectAltNames(certificate).isEmpty()) { return false; } X500Principal principal = certificate.getSubjectX500Principal(); - // RFC 2818 advises using the most specific name for matching. String cn = new DistinguishedNameParser(principal).findMostSpecific("cn"); if (cn != null) { return verifyHostName(host, cn); @@ -80,49 +82,23 @@ public boolean verify(String host, SSLSession session) } } + /** + * Verify as ip address boolean. + * + * @param host the host + * @return the boolean + */ static boolean verifyAsIpAddress(String host) { return VERIFY_AS_IP_ADDRESS.matcher(host).matches(); } /** - * Returns true if {@code certificate} matches {@code ipAddress}. + * All subject alt names list. + * + * @param certificate the certificate + * @return the list */ - private boolean verifyIpAddress(String ipAddress, X509Certificate certificate) - { - List altNames = getSubjectAltNames(certificate, ALT_IPA_NAME); - for (int i = 0, size = altNames.size(); i < size; i++) { - if (ipAddress.equalsIgnoreCase(altNames.get(i))) { - return true; - } - } - return false; - } - - private boolean verifyHostName(String hostName, X509Certificate certificate) - { - hostName = hostName.toLowerCase(Locale.US); - boolean hasDns = false; - List altNames = getSubjectAltNames(certificate, ALT_DNS_NAME); - for (int i = 0, size = altNames.size(); i < size; i++) { - hasDns = true; - if (verifyHostName(hostName, altNames.get(i))) { - return true; - } - } - - if (!hasDns) { - X500Principal principal = certificate.getSubjectX500Principal(); - // RFC 2818 advises using the most specific name for matching. - String cn = new DistinguishedNameParser(principal).findMostSpecific("cn"); - if (cn != null) { - return verifyHostName(hostName, cn); - } - } - - return false; - } - public static List allSubjectAltNames(X509Certificate certificate) { List altIpaNames = getSubjectAltNames(certificate, ALT_IPA_NAME); @@ -173,90 +149,50 @@ private static List getSubjectAltNames(X509Certificate certificate, int */ private boolean verifyHostName(String hostName, String pattern) { - // Basic sanity checks - // Check length == 0 instead of .isEmpty() to support Java 5. if ((hostName == null) || (hostName.length() == 0) || (hostName.startsWith(".")) || (hostName.endsWith(".."))) { - // Invalid domain name return false; } if ((pattern == null) || (pattern.length() == 0) || (pattern.startsWith(".")) || (pattern.endsWith(".."))) { - // Invalid pattern/domain name return false; } - // Normalize hostName and pattern by turning them into absolute domain names if they are not - // yet absolute. This is needed because server certificates do not normally contain absolute - // names or patterns, but they should be treated as absolute. At the same time, any hostName - // presented to this method should also be treated as absolute for the purposes of matching - // to the server certificate. - // www.android.com matches www.android.com - // www.android.com matches www.android.com. - // www.android.com. matches www.android.com. - // www.android.com. matches www.android.com if (!hostName.endsWith(".")) { hostName += '.'; } if (!pattern.endsWith(".")) { pattern += '.'; } - // hostName and pattern are now absolute domain names. pattern = pattern.toLowerCase(Locale.US); - // hostName and pattern are now in lower case -- domain names are case-insensitive. if (!pattern.contains("*")) { - // Not a wildcard pattern -- hostName and pattern must match exactly. return hostName.equals(pattern); } - // Wildcard pattern - - // WILDCARD PATTERN RULES: - // 1. Asterisk (*) is only permitted in the left-most domain name label and must be the - // only character in that label (i.e., must match the whole left-most label). - // For example, *.example.com is permitted, while *a.example.com, a*.example.com, - // a*b.example.com, a.*.example.com are not permitted. - // 2. Asterisk (*) cannot match across domain name labels. - // For example, *.example.com matches test.example.com but does not match - // sub.test.example.com. - // 3. Wildcard patterns for single-label domain names are not permitted. if ((!pattern.startsWith("*.")) || (pattern.indexOf('*', 1) != -1)) { - // Asterisk (*) is only permitted in the left-most domain name label and must be the only - // character in that label return false; } - // Optimization: check whether hostName is too short to match the pattern. hostName must be at - // least as long as the pattern because asterisk must match the whole left-most label and - // hostName starts with a non-empty label. Thus, asterisk has to match one or more characters. if (hostName.length() < pattern.length()) { - // hostName too short to match the pattern. return false; } if ("*.".equals(pattern)) { - // Wildcard pattern for single-label domain name -- not permitted. return false; } - // hostName must end with the region of pattern following the asterisk. String suffix = pattern.substring(1); if (!hostName.endsWith(suffix)) { - // hostName does not end with the suffix return false; } - // Check that asterisk did not match across domain name labels. int suffixStartIndexInHostName = hostName.length() - suffix.length(); if ((suffixStartIndexInHostName > 0) && (hostName.lastIndexOf('.', suffixStartIndexInHostName - 1) != -1)) { - // Asterisk is matching across domain name labels -- not permitted. return false; } - - // hostName matches pattern return true; } } diff --git a/presto-common/src/main/java/com/facebook/presto/common/TelemetryConfig.java b/presto-common/src/main/java/com/facebook/presto/common/TelemetryConfig.java index bab321feb769d..765595d8f23da 100644 --- a/presto-common/src/main/java/com/facebook/presto/common/TelemetryConfig.java +++ b/presto-common/src/main/java/com/facebook/presto/common/TelemetryConfig.java @@ -19,7 +19,7 @@ import static java.util.Objects.requireNonNull; /** - * The type TelemetryConfig to store all the values in telemetry.properties. + * The type TelemetryConfig to store the values from telemetry-tracing.properties. */ public class TelemetryConfig { @@ -31,11 +31,11 @@ public class TelemetryConfig private Integer exporterTimeout; private Integer scheduleDelay; private Double samplingRatio; - private Boolean tracingEnabled = false; - private Boolean spanSampling = false; + private boolean tracingEnabled; + private boolean spanSampling; /** - * The type Telemetry config constants. + * The type TelemetryConfigConstants to store constants. */ public static class TelemetryConfigConstants { @@ -54,7 +54,7 @@ private TelemetryConfig() } /** - * Gets telemetry config. + * Gets the singleton telemetryConfig. * * @return the telemetry config */ @@ -65,7 +65,7 @@ public static TelemetryConfig getTelemetryConfig() } /** - * Sets telemetry properties. + * Sets telemetry properties from the input. * * @param telemetryProperties the telemetry properties */ @@ -91,91 +91,46 @@ public void setTracingEnabled(Boolean tracingEnabled) getTelemetryConfig().tracingEnabled = tracingEnabled; } - /** - * Sets span sampling. - * - * @param spanSampling the span sampling - */ public void setSpanSampling(Boolean spanSampling) { getTelemetryConfig().spanSampling = spanSampling; } - /** - * Gets exporter endpoint. - * - * @return the exporter endpoint - */ public String getTracingBackendUrl() { return this.tracingBackendUrl; } - /** - * Gets max exporter batch size. - * - * @return the max exporter batch size - */ public Integer getMaxExporterBatchSize() { return this.maxExporterBatchSize; } - /** - * Gets max queue size. - * - * @return the max queue size - */ public Integer getMaxQueueSize() { return this.maxQueueSize; } - /** - * Gets exporter timeout. - * - * @return the exporter timeout - */ public Integer getExporterTimeout() { return this.exporterTimeout; } - /** - * Gets schedule delay. - * - * @return the schedule delay - */ public Integer getScheduleDelay() { return this.scheduleDelay; } - /** - * Gets sampling ratio. - * - * @return the sampling ratio - */ public Double getSamplingRatio() { return this.samplingRatio; } - /** - * Gets tracing enabled. - * - * @return the tracing enabled - */ public static Boolean getTracingEnabled() { return getTelemetryConfig().tracingEnabled; } - /** - * Gets span sampling. - * - * @return the span sampling - */ public static Boolean getSpanSampling() { return getTelemetryConfig().spanSampling; diff --git a/presto-common/src/main/java/com/facebook/presto/common/TracingConfig.java b/presto-common/src/main/java/com/facebook/presto/common/TracingConfig.java index f05834e52adbc..b0edb542ecb73 100644 --- a/presto-common/src/main/java/com/facebook/presto/common/TracingConfig.java +++ b/presto-common/src/main/java/com/facebook/presto/common/TracingConfig.java @@ -19,7 +19,7 @@ import javax.annotation.concurrent.Immutable; /** - * The type Tracing config. + * POJO to use with TelemetryResource for the dynamically enable/disable the trace endpoint. */ @Immutable public class TracingConfig @@ -38,11 +38,6 @@ public TracingConfig( this.tracingEnabled = tracingEnabled; } - /** - * Is tracing enabled boolean. - * - * @return the boolean - */ @JsonProperty public boolean isTracingEnabled() { diff --git a/presto-main/src/main/java/com/facebook/presto/Session.java b/presto-main/src/main/java/com/facebook/presto/Session.java index 6349387ba0038..08be4e326554d 100644 --- a/presto-main/src/main/java/com/facebook/presto/Session.java +++ b/presto-main/src/main/java/com/facebook/presto/Session.java @@ -39,7 +39,6 @@ import com.facebook.presto.sql.analyzer.CTEInformationCollector; import com.facebook.presto.sql.planner.optimizations.OptimizerInformationCollector; import com.facebook.presto.sql.planner.optimizations.OptimizerResultCollector; -import com.facebook.presto.telemetry.TracingManager; import com.facebook.presto.transaction.TransactionManager; import com.google.common.collect.ImmutableMap; import com.google.common.collect.ImmutableSet; @@ -67,6 +66,8 @@ import static com.facebook.presto.spi.ConnectorId.createInformationSchemaConnectorId; import static com.facebook.presto.spi.ConnectorId.createSystemTablesConnectorId; import static com.facebook.presto.spi.StandardErrorCode.NOT_FOUND; +import static com.facebook.presto.telemetry.TracingManager.getInvalidSpan; +import static com.facebook.presto.telemetry.TracingManager.spanString; import static com.facebook.presto.util.Failures.checkCondition; import static com.google.common.base.MoreObjects.toStringHelper; import static com.google.common.base.Preconditions.checkArgument; @@ -530,7 +531,7 @@ public String toString() { return toStringHelper(this) .add("queryId", queryId) - .add("querySpan", TracingManager.spanString(querySpan).orElse(null)) + .add("querySpan", spanString(querySpan).orElse(null)) .add("rootSpan", rootSpan.toString()) .add("transactionId", transactionId) .add("user", getUser()) @@ -563,8 +564,8 @@ public static SessionBuilder builder(Session session) public static class SessionBuilder { private QueryId queryId; - private BaseSpan querySpan = TracingManager.getInvalidSpan(); //do not initialize with null - private BaseSpan rootSpan = TracingManager.getInvalidSpan(); //do not initialize with null + private BaseSpan querySpan = getInvalidSpan(); //do not initialize with null + private BaseSpan rootSpan = getInvalidSpan(); //do not initialize with null private TransactionId transactionId; private boolean clientTransactionSupport; private Identity identity; diff --git a/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryModule.java b/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryModule.java index 05bc45425de80..b4c6443cfe96b 100644 --- a/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryModule.java +++ b/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryModule.java @@ -19,9 +19,6 @@ import static org.weakref.jmx.guice.ExportBinder.newExporter; -/** - * The type Telemetry module. - */ public class TelemetryModule implements Module { diff --git a/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryResource.java b/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryResource.java index 0c6ca3b7443b8..ec2ac59e3876d 100644 --- a/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryResource.java +++ b/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryResource.java @@ -30,7 +30,7 @@ import static javax.ws.rs.core.MediaType.APPLICATION_JSON; /** - * The type Telemetry resource. + * The type Telemetry resource holds the end point to enable/disable the traces dynamically. */ @Path("/v1/telemetry") @RolesAllowed({USER, ADMIN}) diff --git a/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryTracingImpl.java b/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryTracingImpl.java index 8338f40c740d1..4260ae03e6897 100644 --- a/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryTracingImpl.java +++ b/presto-main/src/main/java/com/facebook/presto/telemetry/TelemetryTracingImpl.java @@ -23,21 +23,15 @@ import java.util.Optional; /** - * The type Telemetry tracing. + * Default implementation of TelemetryTracing in presto-main for fallback in case Telemetry plugin implementation not loaded. */ public class TelemetryTracingImpl implements TelemetryTracing { - /** - * The constant NAME. - */ public static final String NAME = "otel"; private static final TelemetryTracingImpl INSTANCE = new TelemetryTracingImpl(); - /** - * The type Factory. - */ public static class Factory implements TelemetryFactory { diff --git a/presto-main/src/main/java/com/facebook/presto/telemetry/TracingManager.java b/presto-main/src/main/java/com/facebook/presto/telemetry/TracingManager.java index a15db86f289c1..0b2da113fed13 100644 --- a/presto-main/src/main/java/com/facebook/presto/telemetry/TracingManager.java +++ b/presto-main/src/main/java/com/facebook/presto/telemetry/TracingManager.java @@ -21,25 +21,21 @@ import com.facebook.presto.spi.telemetry.TelemetryTracing; import java.io.File; -import java.io.IOException; -import java.io.InputStream; -import java.nio.file.Files; import java.util.HashMap; import java.util.Map; import java.util.Optional; -import java.util.Properties; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.atomic.AtomicReference; +import static com.facebook.presto.util.PropertiesUtil.loadProperties; import static com.google.common.base.Preconditions.checkArgument; import static com.google.common.base.Preconditions.checkState; import static com.google.common.base.Strings.isNullOrEmpty; -import static com.google.common.collect.Maps.fromProperties; import static java.lang.String.format; import static java.util.Objects.requireNonNull; /** - * OpenTelemetryManager class creates and manages OpenTelemetry and Tracer instances. + * TelemetryManager class creates and manages Telemetry and Tracer instances. */ public class TracingManager { @@ -51,21 +47,22 @@ public class TracingManager private static AtomicReference configuredTelemetryTracing = new AtomicReference<>(new TelemetryTracingImpl()); /** - * adds and registers all the OpenTelemetryFactory implementations to support different configurations + * Adds and registers all the TelemetryFactory implementations using PluginManager to support tracing. * * @param telemetryFactory the telemetry factory */ public void addOpenTelemetryFactory(TelemetryFactory telemetryFactory) { - requireNonNull(telemetryFactory, "openTelemetryFactory is null"); + requireNonNull(telemetryFactory, "telemetryFactory is null"); log.debug("Adding telemetry factory"); if (openTelemetryFactories.putIfAbsent(telemetryFactory.getName(), telemetryFactory) != null) { - throw new IllegalArgumentException(format("openTelemetry factory '%s' is already registered", telemetryFactory.getName())); + throw new IllegalArgumentException(format("Telemetry factory '%s' is already registered", telemetryFactory.getName())); } } /** - * called from PrestoServer for loading the properties after OpenTelemetryManager is bound and injected + * Instantiates required Telemetry instances after loading the plugin implementation. + * Called from PrestoServer after the plugin implementation got loaded. * * @throws Exception the exception */ @@ -76,7 +73,7 @@ public void loadConfiguredOpenTelemetry() Map properties = loadProperties(OPENTELEMETRY_CONFIGURATION); checkArgument( !isNullOrEmpty(properties.get(TRACING_FACTORY_NAME)), - "Opentelemetry configuration %s does not contain %s", + "Telemetry configuration %s does not contain %s", OPENTELEMETRY_CONFIGURATION.getAbsoluteFile(), TRACING_FACTORY_NAME); @@ -87,268 +84,118 @@ public void loadConfiguredOpenTelemetry() properties = new HashMap<>(properties); String openTelemetryFactoryName = properties.remove(TRACING_FACTORY_NAME); - checkArgument(!isNullOrEmpty(openTelemetryFactoryName), "otel-factory.name property must be present"); + checkArgument(!isNullOrEmpty(openTelemetryFactoryName), TRACING_FACTORY_NAME + " property must be present"); TelemetryFactory openTelemetryFactory = openTelemetryFactories.get(openTelemetryFactoryName); - checkState(openTelemetryFactory != null, "Opentelemetry factory %s is not registered", openTelemetryFactoryName); + checkState(openTelemetryFactory != null, "Telemetry factory %s is not registered", openTelemetryFactoryName); this.configuredTelemetryTracing.set((TelemetryTracing) openTelemetryFactory.create()); - log.debug("setting telemetry properties"); + log.debug("setting telemetry-tracing properties"); TelemetryConfig.getTelemetryConfig().setTelemetryProperties(properties); configuredTelemetryTracing.get().loadConfiguredOpenTelemetry(); } } - private static Map loadProperties(File file) - throws IOException - { - Properties properties = new Properties(); - try (InputStream in = Files.newInputStream(file.toPath())) { - properties.load(in); - } - return fromProperties(properties); - } - - /** - * Sets configured telemetry tracing. - * - * @param telemetryTracing the telemetry tracing - */ public static void setConfiguredTelemetryTracing(TelemetryTracing telemetryTracing) { TracingManager.configuredTelemetryTracing.set(telemetryTracing); } - /** - * Gets current context wrap. - * - * @param runnable the runnable - * @return the current context wrap - */ public static Runnable getCurrentContextWrap(Runnable runnable) { return configuredTelemetryTracing.get().getCurrentContextWrap(runnable); } - /** - * Is recording boolean. - * - * @return the boolean - */ public static boolean isRecording() { return configuredTelemetryTracing.get().isRecording(); } - /** - * Gets headers map. - * - * @param span the span - * @return the headers map - */ public static Map getHeadersMap(BaseSpan span) { return configuredTelemetryTracing.get().getHeadersMap(span); } - /** - * End span on error. - * - * @param querySpan the query span - * @param throwable the throwable - */ public static void endSpanOnError(BaseSpan querySpan, Throwable throwable) { configuredTelemetryTracing.get().endSpanOnError(querySpan, throwable); } - /** - * Add event. - * - * @param querySpan the query span - * @param eventName the event name - */ public static void addEvent(BaseSpan querySpan, String eventName) { configuredTelemetryTracing.get().addEvent(querySpan, eventName); } - /** - * Add event. - * - * @param querySpan the query span - * @param eventName the event name - * @param eventState the event state - */ public static void addEvent(BaseSpan querySpan, String eventName, String eventState) { configuredTelemetryTracing.get().addEvent(querySpan, eventName, eventState); } - /** - * Sets attributes. - * - * @param span the span - * @param attributes the attributes - */ public static void setAttributes(BaseSpan span, Map attributes) { configuredTelemetryTracing.get().setAttributes(span, attributes); } - /** - * Record exception. - * - * @param querySpan the query span - * @param message the message - * @param runtimeException the runtime exception - * @param errorCode the error code - */ public static void recordException(BaseSpan querySpan, String message, RuntimeException runtimeException, ErrorCode errorCode) { configuredTelemetryTracing.get().recordException(querySpan, message, runtimeException, errorCode); } - /** - * Sets success. - * - * @param querySpan the query span - */ public static void setSuccess(BaseSpan querySpan) { configuredTelemetryTracing.get().setSuccess(querySpan); } - /** - * Gets invalid span. - * - * @return the invalid span - */ -//GetSpans public static BaseSpan getInvalidSpan() { return configuredTelemetryTracing.get().getInvalidSpan(); } - /** - * Gets root span. - * - * @return the root span - */ public static BaseSpan getRootSpan() { return configuredTelemetryTracing.get().getRootSpan(); } - /** - * Gets span. - * - * @param spanName the span name - * @return the span - */ public static BaseSpan getSpan(String spanName) { return configuredTelemetryTracing.get().getSpan(spanName); } - /** - * Gets span. - * - * @param traceParent the trace parent - * @param spanName the span name - * @return the span - */ public static BaseSpan getSpan(String traceParent, String spanName) { return configuredTelemetryTracing.get().getSpan(traceParent, spanName); } - /** - * Gets span. - * - * @param parentSpan the parent span - * @param spanName the span name - * @param attributes the attributes - * @return the span - */ public static BaseSpan getSpan(BaseSpan parentSpan, String spanName, Map attributes) { return configuredTelemetryTracing.get().getSpan(parentSpan, spanName, attributes); } - /** - * Span string optional. - * - * @param span the span - * @return the optional - */ public static Optional spanString(BaseSpan span) { return configuredTelemetryTracing.get().spanString(span); } - //Scoped Span - - /** - * starts a basic span and passes it to overloaded method. This method is used for creating basic spans with no attributes. - * - * @param name name of span to be created - * @param skipSpan optional parameter to implement span sampling by skipping the current span export - * @return base span - */ public static BaseSpan scopedSpan(String name, Boolean... skipSpan) { return configuredTelemetryTracing.get().scopedSpan(name, skipSpan); } - /** - * creates a ScopedSpan with the current span. This method is used when we manually create spans in the classes and - * set attributes to them before passing to the Scopedspan. - * - * @param span created span instance - * @param skipSpan optional parameter to implement span sampling by skipping the current span export - * @return base span - */ public static BaseSpan scopedSpan(BaseSpan span, Boolean... skipSpan) { return configuredTelemetryTracing.get().scopedSpan(span, skipSpan); } - /** - * Scoped span base span. - * - * @param parentSpan the parent span - * @param spanName the span name - * @param attributes the attributes - * @param skipSpan the skip span - * @return the base span - */ public static BaseSpan scopedSpan(BaseSpan parentSpan, String spanName, Map attributes, Boolean... skipSpan) { return configuredTelemetryTracing.get().scopedSpan(parentSpan, spanName, attributes, skipSpan); } - /** - * Scoped span base span. - * - * @param parentSpan the parent span - * @param spanName the span name - * @param skipSpan the skip span - * @return the base span - */ public static BaseSpan scopedSpan(BaseSpan parentSpan, String spanName, Boolean... skipSpan) { return configuredTelemetryTracing.get().scopedSpan(parentSpan, spanName, skipSpan); } - /** - * Scoped span base span. - * - * @param spanName the span name - * @param attributes the attributes - * @param skipSpan the skip span - * @return the base span - */ public static BaseSpan scopedSpan(String spanName, Map attributes, Boolean... skipSpan) { return configuredTelemetryTracing.get().scopedSpan(spanName, attributes, skipSpan); diff --git a/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/OpenTelemetryTracingImpl.java b/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/OpenTelemetryTracingImpl.java index 45081d4dff8a2..4c53f24457922 100644 --- a/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/OpenTelemetryTracingImpl.java +++ b/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/OpenTelemetryTracingImpl.java @@ -86,7 +86,7 @@ public void createTracer() } /** - * Create opentelemetry instance + * Create and set the opentelemetry instance. * * @return {@link OpenTelemetry} */ @@ -134,21 +134,11 @@ public OpenTelemetry createOpenTelemetry() return openTelemetry; } - /** - * Sets open telemetry. - * - * @param configuredOpenTelemetry the configured open telemetry - */ public static void setOpenTelemetry(OpenTelemetry configuredOpenTelemetry) { OpenTelemetryTracingImpl.configuredOpenTelemetry = configuredOpenTelemetry; } - /** - * Sets tracer. - * - * @param tracer the tracer - */ public static void setTracer(Tracer tracer) { OpenTelemetryTracingImpl.tracer = tracer; @@ -166,44 +156,21 @@ public Runnable getCurrentContextWrap(Runnable runnable) return Context.current().wrap(runnable); } - /** - * get current context . - * - * @return Context - */ private static Context getCurrentContext() { return Context.current(); } - /** - * get context from the span. - * - * @param tracingSpan runnable - * @return Context - */ private static Context getCurrentContextWith(TracingSpan tracingSpan) { return Context.current().with(tracingSpan.getSpan()); } - /** - * get the context from the span or current context. - * - * @param span span - * @return Context - */ private static Context getContext(TracingSpan span) { return span != null ? getCurrentContextWith(span) : getCurrentContext(); } - /** - * get the context from the traceParent string. - * - * @param traceParent traceParent - * @return Context - */ private static Context getContext(String traceParent) { TextMapPropagator propagator = configuredOpenTelemetry.getPropagators().getTextMapPropagator(); @@ -222,7 +189,7 @@ public boolean isRecording() } /** - * returns headers map from the input span. + * Returns headers map from the input span. * * @param span span * @return Map @@ -239,7 +206,7 @@ public Map getHeadersMap(TracingSpan span) } /** - * ends span on error with recorded exceptions. + * Ends span by updating the status to error and record input exception. * * @param span querySpan * @param throwable throwable @@ -256,7 +223,7 @@ public void endSpanOnError(TracingSpan span, Throwable throwable) } /** - * add event to the span. + * Add the input event to the input span. * * @param span span * @param eventName eventName @@ -270,7 +237,7 @@ public void addEvent(TracingSpan span, String eventName) } /** - * add event to the span. + * Add the input event to the input span. * * @param span span * @param eventName eventName @@ -285,7 +252,7 @@ public void addEvent(TracingSpan span, String eventName, String eventState) } /** - * set attributes to the span. + * Sets the attributes map to the input span. * * @param span span * @param attributes attributes @@ -299,7 +266,7 @@ public void setAttributes(TracingSpan span, Map attributes) } /** - * record exception to the span. + * Records exception to the input span with error code and message. * * @param span span * @param message message @@ -319,7 +286,7 @@ public void recordException(TracingSpan span, String message, RuntimeException r } /** - * mark success to span. + * Sets the status of the input span to success. * * @param span span */ @@ -333,7 +300,7 @@ public void setSuccess(TracingSpan span) //Tracing spans /** - * To get an invalid span. + * Returns an invalid Span. An invalid Span is used when tracing is disabled. * @return TracingSpan */ @Override @@ -343,7 +310,7 @@ public TracingSpan getInvalidSpan() } /** - * To get root span. + * Creates and returns the root span. * @return TracingSpan */ @Override @@ -354,7 +321,7 @@ public TracingSpan getRootSpan() } /** - * To get span with name. + * Creates and returns the span with input name. * @param spanName name of span to be created * @return TracingSpan */ @@ -366,7 +333,7 @@ public TracingSpan getSpan(String spanName) } /** - * To get a new span with name from the trace parent string. + * Creates and returns the span with input name and parent context from input. * @param traceParent trace parent string. * @param spanName name of the span to be created. * @return TracingSpan @@ -380,7 +347,7 @@ public TracingSpan getSpan(String traceParent, String spanName) } /** - * To get a new span with name from the parent span. + * Creates and returns the span with input name, attributes and parent span as the input span. * @param parentSpan parent span. * @param spanName name of the span to be created. * @param attributes input attributes to set in span. @@ -394,12 +361,6 @@ public TracingSpan getSpan(TracingSpan parentSpan, String spanName, Map attributes) { attributes.forEach(spanBuilder::setAttribute); @@ -407,7 +368,7 @@ private static SpanBuilder setAttributes(SpanBuilder spanBuilder, Map */ @@ -424,7 +385,7 @@ public Optional spanString(TracingSpan span) //Scoped Spans /** - * To get ScopedSpan with name. + * Creates and returns the ScopedSpan with input name. * @param spanName name of span to be created * @param skipSpan optional parameter to implement span sampling by skipping the current span export * @return ScopedSpan @@ -440,7 +401,7 @@ public ScopedSpan scopedSpan(String spanName, Boolean... skipSpan) } /** - * To get ScopedSpan from the parent span instance. + * Creates and returns the ScopedSpan with parent span as input span. * @param parentSpan parent span * @param skipSpan optional parameter to implement span sampling by skipping the current span export * @return ScopedSpan @@ -456,7 +417,7 @@ public ScopedSpan scopedSpan(TracingSpan parentSpan, Boolean... skipSpan) } /** - * To get ScopedSpan from the parent span instance with name and also setting the input attributes. + * Creates and returns the ScopedSpan with input name, attributes and parent span as the input span. * @param parentSpan parent span * @param skipSpan optional parameter to implement span sampling by skipping the current span export * @return ScopedSpan @@ -476,7 +437,7 @@ public ScopedSpan scopedSpan(TracingSpan parentSpan, String spanName, Map { diff --git a/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/OpenTelemetryFactoryImpl.java b/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/OpenTelemetryFactoryImpl.java index fbb3b0f103378..2f70622394d79 100644 --- a/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/OpenTelemetryFactoryImpl.java +++ b/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/OpenTelemetryFactoryImpl.java @@ -23,7 +23,7 @@ public class OpenTelemetryFactoryImpl { /** * uniquely identify all OpenTelemetryFactory implementations. This property is checked against the one passed in - * telemetry.properties file during registration + * telemetry-tracing.properties file during registration * @return String */ @Override diff --git a/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/ScopedSpan.java b/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/ScopedSpan.java index 2f95dcde144b9..d1043a91561dd 100644 --- a/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/ScopedSpan.java +++ b/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/ScopedSpan.java @@ -21,7 +21,8 @@ import java.util.Objects; /** - * The type Scoped span. + * ScopedSpan implements BaseSpan and holds the actual sdk span. + * ScopedSpan implements AutoCloseable and can be used within a try-with-resources block. */ public final class ScopedSpan implements BaseSpan diff --git a/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/TracingSpan.java b/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/TracingSpan.java index 3c27a93263ae0..df66cfa9fab4c 100644 --- a/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/TracingSpan.java +++ b/presto-open-telemetry/src/main/java/com/facebook/presto/opentelemetry/tracing/TracingSpan.java @@ -17,7 +17,8 @@ import io.opentelemetry.api.trace.Span; /** - * The type Tracing span. + * TracingSpan implements BaseSpan and holds the actual sdk span. + * TracingSpan can be use where we know the scope and can manually start and end. */ public class TracingSpan implements BaseSpan diff --git a/presto-open-telemetry/src/main/java/com/facebook/presto/plugin/opentelemetry/OpenTelemetryPlugin.java b/presto-open-telemetry/src/main/java/com/facebook/presto/plugin/opentelemetry/OpenTelemetryPlugin.java index 123ab6634225b..bc7f239399d4b 100644 --- a/presto-open-telemetry/src/main/java/com/facebook/presto/plugin/opentelemetry/OpenTelemetryPlugin.java +++ b/presto-open-telemetry/src/main/java/com/facebook/presto/plugin/opentelemetry/OpenTelemetryPlugin.java @@ -19,9 +19,6 @@ import com.facebook.presto.testing.TestingOpenTelemetryFactoryImpl; import com.google.common.collect.ImmutableList; -/** - * The type Open telemetry plugin. - */ public class OpenTelemetryPlugin implements Plugin { diff --git a/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/BaseSpan.java b/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/BaseSpan.java index f7938a74ccaf4..e7876d22a3b07 100644 --- a/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/BaseSpan.java +++ b/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/BaseSpan.java @@ -14,7 +14,7 @@ package com.facebook.presto.spi.telemetry; /** - * The interface Base span. + * The SPI BaseSpan implemented by TracingSpan and ScopedSpan. */ public interface BaseSpan extends AutoCloseable @@ -25,9 +25,6 @@ default void close() return; } - /** - * End. - */ default void end() { return; diff --git a/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/TelemetryFactory.java b/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/TelemetryFactory.java index 43f54fbe073ed..1cd71f02a5416 100644 --- a/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/TelemetryFactory.java +++ b/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/TelemetryFactory.java @@ -14,23 +14,13 @@ package com.facebook.presto.spi.telemetry; /** - * The interface Telemetry factory. + * The SPI TelemetryFactory provides different Telemetry implementations . * * @param the type parameter */ public interface TelemetryFactory { - /** - * Gets name. - * - * @return the name - */ String getName(); - /** - * Create t. - * - * @return the t - */ T create(); } diff --git a/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/TelemetryTracing.java b/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/TelemetryTracing.java index 5a6a8a910fbb0..272ac292bd59c 100644 --- a/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/TelemetryTracing.java +++ b/presto-spi/src/main/java/com/facebook/presto/spi/telemetry/TelemetryTracing.java @@ -19,7 +19,7 @@ import java.util.Optional; /** - * The interface Telemetry tracing. + * The SPI TelemetryTracing is implemented by the required serviceability framework. * * @param the type parameter * @param the type parameter @@ -27,7 +27,7 @@ public interface TelemetryTracing { /** - * Load configured open telemetry. + * Instantiates required Telemetry instances after loading the plugin implementation. */ void loadConfiguredOpenTelemetry(); @@ -40,14 +40,14 @@ public interface TelemetryTracing Runnable getCurrentContextWrap(Runnable runnable); /** - * Is recording boolean. + * Returns true if this Span records tracing events. * * @return the boolean */ boolean isRecording(); /** - * Gets headers map. + * Returns headers map from the input span. * * @param span the span * @return the headers map @@ -55,7 +55,7 @@ public interface TelemetryTracing Map getHeadersMap(T span); /** - * End span on error. + * Ends span by updating the status to error and record input exception. * * @param querySpan the query span * @param throwable the throwable @@ -63,7 +63,7 @@ public interface TelemetryTracing void endSpanOnError(T querySpan, Throwable throwable); /** - * Add event. + * Add the input event to the input span. * * @param span the span * @param eventName the event name @@ -71,16 +71,16 @@ public interface TelemetryTracing void addEvent(T span, String eventName); /** - * Add event. + * Add the input event to the input span. * - * @param querySpan the query span + * @param span the query span * @param eventName the event name * @param eventState the event state */ - void addEvent(T querySpan, String eventName, String eventState); + void addEvent(T span, String eventName, String eventState); /** - * Sets attributes. + * Sets the attributes map to the input span. * * @param span the span * @param attributes the attributes @@ -88,40 +88,40 @@ public interface TelemetryTracing void setAttributes(T span, Map attributes); /** - * Record exception. + * Records exception to the input span with error code and message. * - * @param querySpan the query span + * @param span the query span * @param message the message * @param runtimeException the runtime exception * @param errorCode the error code */ - void recordException(T querySpan, String message, RuntimeException runtimeException, ErrorCode errorCode); + void recordException(T span, String message, RuntimeException runtimeException, ErrorCode errorCode); /** - * Sets success. + * Sets the status of the input span to success. * - * @param querySpan the query span + * @param span the query span */ - void setSuccess(T querySpan); + void setSuccess(T span); //GetSpans /** - * Gets invalid span. + * Returns an invalid Span. An invalid Span is used when tracing is disabled. * * @return the invalid span */ T getInvalidSpan(); /** - * Gets root span. + * Creates and returns the root span. * * @return the root span */ T getRootSpan(); /** - * Gets span. + * Creates and returns the span with input name. * * @param spanName the span name * @return the span @@ -129,7 +129,7 @@ public interface TelemetryTracing T getSpan(String spanName); /** - * Gets span. + * Creates and returns the span with input name and parent context from input. * * @param traceParent the trace parent * @param spanName the span name @@ -138,7 +138,7 @@ public interface TelemetryTracing T getSpan(String traceParent, String spanName); /** - * Gets span. + * Creates and returns the span with input name, attributes and parent span as the input span. * * @param parentSpan the parent span * @param spanName the span name @@ -148,7 +148,7 @@ public interface TelemetryTracing T getSpan(T parentSpan, String spanName, Map attributes); /** - * Span string optional. + * Returns the span info as string. * * @param span the span * @return the optional @@ -158,7 +158,7 @@ public interface TelemetryTracing //scoped spans /** - * Scoped span u. + * Creates and returns the ScopedSpan with input name. * * @param name the name * @param skipSpan the skip span @@ -167,7 +167,7 @@ public interface TelemetryTracing U scopedSpan(String name, Boolean... skipSpan); /** - * Scoped span u. + * Creates and returns the ScopedSpan with parent span as input span. * * @param span the span * @param skipSpan the skip span @@ -176,7 +176,7 @@ public interface TelemetryTracing U scopedSpan(T span, Boolean... skipSpan); /** - * Scoped span u. + * Creates and returns the ScopedSpan with input name, attributes and parent span as the input span. * * @param parentSpan the parent span * @param spanName the span name @@ -187,7 +187,7 @@ public interface TelemetryTracing U scopedSpan(T parentSpan, String spanName, Map attributes, Boolean... skipSpan); /** - * Scoped span u. + * Creates and returns the ScopedSpan with input name and the parent span as input span. * * @param parentSpan the parent span * @param spanName the span name @@ -197,7 +197,7 @@ public interface TelemetryTracing U scopedSpan(T parentSpan, String spanName, Boolean... skipSpan); /** - * Scoped span u. + * Creates and returns the ScopedSpan with input name and attributes. * * @param spanName the span name * @param attributes the attributes