Інструментування
Інструментування — це процес додавання коду спостереження до вашого застосунку.
Якщо ви інструментуєте застосунок, вам потрібно використовувати OpenTelemetry SDK для вашої мови програмування. Потім ви будете використовувати SDK для ініціалізації OpenTelemetry та API для інструментування вашого коду. Це буде генерувати телеметрію з вашого застосунку та будь-якої бібліотеки, яку ви встановили, що також містить інструментування.
Якщо ви інструментуєте бібліотеку, встановіть лише пакет OpenTelemetry API для вашої мови програмування. Ваша бібліотека не буде генерувати телеметрію самостійно. Вона буде генерувати телеметрію лише тоді, коли буде частиною застосунку, що використовує OpenTelemetry SDK. Для отримання додаткової інформації про інструментування бібліотек дивіться Бібліотеки.
Для отримання додаткової інформації про OpenTelemetry API та SDK дивіться специфікацію.
Налаштування
Додайте наступні залежності до вашого проєкту:
opentelemetry_api: містить інтерфейси, які ви будете використовувати для інструментування вашого коду. Такі речі, якTracer.with_spanіTracer.set_attribute, визначені тут.opentelemetry: містить SDK, який реалізує інтерфейси, визначені в API. Без нього всі функції в API будуть no-ops.
# mix.exs
def deps do
[
{:opentelemetry, "~> 1.3"},
{:opentelemetry_api, "~> 1.2"},
]
end
Трейси
Ініціалізація Трейсингу
Щоб почати трейсинг, потрібен TracerProvider для створення Tracer. Коли OpenTelemetry SDK Application (opentelemetry) запускається, він запускає та налаштовує глобальний TracerProvider. Tracer для кожного завантаженого OTP Application створюється після запуску TracerProvider.
Якщо TracerProvider не був успішно створений (наприклад, застосунок opentelemetry не запущений або не вдалося запустити), OpenTelemetry API для трейсингу використовуватиме no-op реалізацію і не буде генерувати дані.
Отримання Трейсера
Кожен OTP Application має Tracer, створений для нього, коли запускається застосунок opentelemetry. Імʼя та версія кожного Tracer такі ж, як імʼя та версія OTP Application, в якому використовується Tracer. Якщо виклик для використання Tracer не знаходиться в модулі, наприклад, при використанні інтерактивної оболонки, використовується Tracer з порожнім імʼям та версією.
Запис створеного Tracer можна знайти за імʼям модуля в OTP Application:
opentelemetry:get_application_tracer(?MODULE)
:opentelemetry.get_application_tracer(__MODULE__)
Таким чином, макроси Erlang та Elixir для запуску та оновлення Spans автоматично отримують Tracer без необхідності передавати змінну в кожному виклику.
Створення Відрізків
Тепер, коли у вас є ініціалізовані Tracer, ви можете створювати Відрізки.
?with_span(main, #{}, fun() ->
%% do work here.
%% when this function returns the Span ends
end).
require OpenTelemetry.Tracer
...
OpenTelemetry.Tracer.with_span :main do
# do work here
# when the block ends the Span ends
end
Наведений вище приклад коду показує, як створити активний Відрізок, що є найпоширенішим типом Span для створення.
Створення вкладених Відрізків
parent_function() ->
?with_span(parent, #{}, fun child_function/0).
child_function() ->
%% this is the same process, so the span parent set as the active
%% span in the with_span call above will be the active span in this function
?with_span(child, #{},
fun() ->
%% do work here. when this function returns, child will complete.
end).
require OpenTelemetry.Tracer
def parent_function() do
OpenTelemetry.Tracer.with_span :parent do
child_function()
end
end
def child_function() do
# this is the same process, so the span :parent set as the active
# span in the with_span call above will be the active span in this function
OpenTelemetry.Tracer.with_span :child do
## do work here. when this function returns, :child will complete.
end
end
Відрізки в окремих процесах
Приклади в попередньому розділі були відрізками з відношенням пращур-нащадок в межах одного процесу, де пращур доступний у словнику процесу при створенні дочірнього відрізка. Використання словника процесу таким чином неможливе при переході між процесами, або шляхом створення нового процесу, або відправленням повідомлення до наявного процесу. Замість цього контекст повинен бути переданий вручну як змінна.
Щоб передати відрізки між процесами, нам потрібно запустити відрізок, який не повʼязаний з конкретним процесом. Це можна зробити за допомогою макросу start_span. На відміну від with_span, макрос start_span не встановлює новий відрізок як активний відрізок у контексті словника процесу.
Звʼязування відрізка як пращура до нащадка в новому процесі можна зробити шляхом прикріплення контексту та встановлення нового відрізка як активного в процесі. Весь контекст повинен бути прикріплений, щоб не втратити інші дані телеметрії, такі як baggage.
SpanCtx = ?start_span(child),
Ctx = otel_ctx:get_current(),
proc_lib:spawn_link(fun() ->
otel_ctx:attach(Ctx),
?set_current_span(SpanCtx),
%% do work here
?end_span(SpanCtx)
end),
span_ctx = OpenTelemetry.Tracer.start_span(:child)
ctx = OpenTelemetry.Ctx.get_current()
task = Task.async(fn ->
OpenTelemetry.Ctx.attach(ctx)
OpenTelemetry.Tracer.set_current_span(span_ctx)
# do work here
# end span here
OpenTelemetry.Tracer.end_span(span_ctx)
end)
_ = Task.await(task)
Звʼязування нового Відрізка
Відрізок може бути створений з нульовою або більше кількістю Span Links, які повʼязують його з іншим Span. Span Link потребує контексту Span для створення.
Parent = ?current_span_ctx,
proc_lib:spawn_link(fun() ->
%% a new process has a new context so the span created
%% by the following `with_span` will have no parent
Link = opentelemetry:link(Parent),
?with_span('other-process', #{links => [Link]},
fun() -> ok end)
end),
parent = OpenTelemetry.Tracer.current_span_ctx()
task = Task.async(fn ->
# a new process has a new context so the span created
# by the following `with_span` will have no parent
link = OpenTelemetry.link(parent)
Tracer.with_span :"my-task", %{links: [link]} do
:hello
end
end)
Додавання атрибутів до Відрізка
Атрибути дозволяють прикріплювати пари ключ/значення до відрізка, щоб він містив більше інформації про поточну операцію, яку він відстежує.
Наступний приклад показує два способи встановлення атрибутів на відрізок, встановлюючи атрибут у параметрах запуску, а потім знову за допомогою set_attributes у тілі операції відрізка:
?with_span(my_span, #{attributes => [{'start-opts-attr', <<"start-opts-value">>}]},
fun() ->
?set_attributes([{'my-attribute', <<"my-value">>},
{another_attribute, <<"value-of-attribute">>}])
end)
Tracer.with_span :span_1, %{attributes: [{:"start-opts-attr", <<"start-opts-value">>}]} do
Tracer.set_attributes([{:"my-attributes", "my-value"},
{:another_attribute, "value-of-attributes"}])
end
Семантичні атрибути
Семантичні Атрибути — це атрибути, визначені Специфікацією OpenTelemetry, щоб забезпечити спільний набір ключів атрибутів для різних мов, фреймворків та середовищ виконання для загальних концепцій, таких як HTTP методи, коди статусу, агенти користувача та інше. Ці ключі атрибутів генеруються зі специфікації та надаються в opentelemetry_semantic_conventions.
Наприклад, інструментування для HTTP клієнта або сервера повинно включати семантичні атрибути, такі як схема URL:
-include_lib("opentelemetry_semantic_conventions/include/trace.hrl").
?with_span(my_span, #{attributes => [{?HTTP_SCHEME, <<"https">>}]},
fun() ->
...
end)
alias OpenTelemetry.SemanticConventions.Trace, as: Trace
Tracer.with_span :span_1, %{attributes: [{Trace.http_scheme(), <<"https">>}]} do
end
Додавання подій
Подія Відрізка — це повідомлення, яке можна прочитати людина, у Відрізку, що являє собою дискретну подію без тривалості, яку можна відстежити за допомогою одного часового відбитка. Ви можете думати про це як про примітивний лог.
?add_event(<<"Gonna try it">>),
%% Do the thing
?add_event(<<"Did it!">>),
Tracer.add_event("Gonna try it")
%% Do the thing
Tracer.add_event("Did it!")
Події також можуть мати власні атрибути:
?add_event(<<"Process exited with reason">>, [{pid, Pid)}, {reason, Reason}]))
Tracer.add_event("Process exited with reason", pid: pid, reason: Reason)
Встановлення статусу Відрізка
Статус можна встановити на Відрізок, зазвичай використовується для вказівки, що Відрізок не завершився успішно — StatusCode.ERROR. У рідкісних випадках ви можете перевизначити статус помилки на StatusCode.OK, але не встановлюйте StatusCode.OK на успішно завершених відрізках.
Статус можна встановити в будь-який час до завершення відрізка:
-include_lib("opentelemetry_api/include/opentelemetry.hrl").
?set_status(?OTEL_STATUS_ERROR, <<"this is not ok">>)
Tracer.set_status(:error, "this is not ok")
Метрики
API метрик, який знаходиться в apps/opentelemetry_experimental_api репозиторію opentelemetry-erlang, наразі нестабільний, документація TBA.
Логи
API логів, який знаходиться в apps/opentelemetry_experimental_api репозиторію opentelemetry-erlang, наразі нестабільний, документація TBA.
Наступні кроки
Вам також потрібно буде налаштувати відповідний експортер для експорту ваших даних телеметрії до одного або більше бекендів телеметрії.
Відгук
Чи це було корисним?
Дякуємо. Ми цінуємо ваші відгуки!
Будь ласка, дайте нам знати як ми можемо покращити цю сторінку. Ми цінуємо ваші відгуки!